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Surprisingly, people are still 
building Office solutions 
without Office 2000 Developer. 





ker 


Where do you want to go today?® 





Microsoft’ Office 2000 Developer is the edition of Office created specifically for developers, 
with tools to help you easily build, deploy, and manage customized solutions. The Data 


Environment Designer lets you visually map out how your code connects to external data. 





The built-in Code Librarian provides easy access to and storage of commonly written code. 
And for even greater productivity, printed documentation and sample code come right in the box. To learn 


more about all the tools in Office 2000 Developer, visit us at msdn.microsoft.com/officedev 


©1999 Microsoft Corporation. All rights reserved. Microsoft and Where do you want to go today? are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. 





CodeWMfright 6.0 








The Programmer's Editing System — 


The CodeWright System MAP 


"IDE's are compilers. 
CodeWright is THE 
Editor." 

--Brand Kvavle 

Black Diamond Software 

www.blackdiamond.com 


Immediately become productive 

- by choosing a familiar keymap in 

- the SuperEditor -- the new 
generation editor with 

| CodeSense™ intelligence. 

| Accelerate productivity with 

| preconfigured Power Tools that 

| preferences. Personalize 
CodeWright's interface to 
accommodate your Workstyle. 
Simplify your development by 
integrating your compilers, 
debuggers and other essential 
tools into a unified environment. 
Plus, CodeWright can be integrated 

_ with IDEs. Organize and view 
existing code and projects with 

Project Viewers. Extend 
CodeWright to meet special 
requirements. Accommodate your 
imagination using ChromaCoding”™ 
lexers, macros and DLLs. 
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Super Editor 


*CodeSense™ 

¢eButton Links 

¢Complete Print Management 
eExacting Search and Replace 
eLanguage Specific Behavior 
¢Enhanced Word Wrap 
¢Familiar Keymaps 


Application Conduits 


eIDE Synchronization Conduit 
°External Conduits 
¢eCompiler/Debugger Conduit 
¢Version Control Conduit 


Project Viewers 


¢eOutline View 

Project View 

°File View 

¢Bookmarks View 
eCodeFolio™ View 

Import Visual Studio Projects 


For a complete list 
and explanation of 
features please go to: 
Www .premia.com/ 
products/overview 


Power Tools 


° CodioFolio™ 

¢Multiple Clipboards 

¢ Differencing/Merging 
¢Enhanced Spell Checking 
¢Keystroke Macros 

¢Code Beautifier 


WorkStyle Controls 


«View Setups 
*Interface Customization 
«Configuration Wizards 
eDocument Window Manager 
*Help System Setup 


Extension Foundation 


¢eLanguage ChromaCoding™ 
¢CodeWright API 
¢Macros: API, Perl, AppBasic 


IntelliSense is a trademark of Microsoft Corporation. 
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That's exactly why you 


will switch to CodeWright. 





Developers say things like, "I can't 
switch editors, | have used mine for 
years." Premia would have it no 
other way. Thousands of new 
developers make the switch to 
CodeWright each year. With highly 
customizable tools that can emulate 
their old editors, and the power of 
CodeWright, developers gain the 
best of both worlds and become 
instant converts. That's why over a 
hundred thousand developers say 
"CodeWright is my editor." 


Why CodeWright 
becomes your editor. 


Use CodeWright straight out of 
the box with pre-configured 
settings for your languages, 
compilers and Microsoft and 
Borland IDEs. Everything you like 
about your existing or older 
generation editor ts intact. For 
example, use CodeWright's pre- 
set key mapping to emulate CUA, 
vi, EMACS, Brief and others. In 
addition, you have the option to 
rapidly customize settings on over 
30 integrated editing features and 
tools. CodeWright becomes your 
editor in every sense of the word. 


You and 
your team will write 
better code faster. 


CodeWright 6.0 is a system of 
integrated editing tools and facilities 
that boost your productivity as you 
write code in virtually any language. 
Use it standalone with your 
compiler and debuggers or 
integrated with MicrosoftVisual 
Studio or Borland IDEs. 





Mere editors are now 
out of date. You must 
have an editing system. 


Programmers of commercial 
applications, information and 
embedded systems have more 
reason to make CodeWright 6.0 
their editor with new powerful 
features like CodeSense™ and 
CodeFolio™ 


CodeSense" is like 


intelliiSense™on steroids. 
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Make your code safer and more accurate with 
CodeSense™ technology, new for 6.0. Graphical symbols 
distinguish parts of code and Goto buttons take you to 
their definitions. CodeSense™ is intelligent code 
completion taken to the next level. 


CodeFolio™ makes code 
reuse smart and fast. 





Give your team a shared view of your commonly used 
code with CodeFolio™. This ultimate code-reuse too! 
provides a folder and file view of code and other text, 
enabling not only quick placement but also macro 
expansion and prompted input as you drag and drop. 


premia 


Passion and 
loyalty about 

a development 
tool? When 

/t comes to 
your editor, 
absolutely. 

You want your 
editor! That's 
why you wil/ 
guickly become a fiercely 
loyal CodeWright aficionado. 
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FEATURES 


JINI AND NETWORK-ENABLED DEVICES 

by Hinkmond Wong 

Jini is a technology designed to let anyone connect any device to any network in a straightforward 
manner. Hinkmond shows how you can use Sun’s EmbeddedJava tools to build a system that 
incorporates Jini technology into small memory footprint, network-enabled devices. 


INTERNET TELEPHONY PROTOCOLS 

by Linden deCarmo 

Linden examines the strengths and weaknesses of SIP and H.323, the two dominant “Voice over 
the Internet” protocols. He also takes a look at a new challenger— the Media Gateway Control 
Protocol. 


X.509 CERTIFICATES 

by Paul Tremblett 

Paul unravels X.509 certificates, one of the most popular computer security standards specifying the 
contents of digital certificates, by showing how you can decode and display them in a readable form. 


THE HTTPSYNC INCREMENTAL UPDATE UTILITY 

by Forrest J. Cavalier III 

HTTPsync is client-side-only software that performs fast and efficient incremental updates to 
synchronize collections of files. And only the standard features of HTTP are used. 


JAVA, SYNCHRONIZATION, & THE PALMPILOT 

by Tilo Christ 

Tilo’s SyncBuilder framework lets you write Java applications that communicate with Palm 
Computing devices and that run on any platform. 








Photography by Pat Johnson Studios. 


EMBEDDED SYSTEMS 


fadmnetcast PROTOCOLS FOR NICHE AREA NETWORKS 68 
by Jaromir Chocholac 

SimpleChat, the Niche Area Network protocol Jaromir introduces here, is designed for 

applications where cost efficiency is more important than very high data rates. 









USENIX Technical Conference 


SD ’99 Conference 

Al Stevens and Herb Schildt on Tour 

Netscape Gecko: INTERNET PROGRAMMING 

Building an Open-Source Browser 

Understanding Enterprise JavaBeans AN ARCHITECTURE FOR WEB SERVICES 80 
by David Houlding 


For more see 


ddj.com/technetcast/ David discusses an architecture that facilitates both the publication of distributed object 


services on the Web and the subsequent reuse of these services by application developers. 
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PROGRAMMER'S TOOLCHEST 


EXAMINING MICROSOFT’S SPEECH SDK 86 


by Peter Davis 

Peter shows how to use the Microsoft Speech SDK to voice-enable your 
Windows apps by adding command-and-control voice recognition to 
applications. 


COLUMNS 


PROGRAMMING PARADIGMS 93 


by Michael Swaine 
1984— the year, not the book—was a watershed in the history of personal 
computing. 


C PROGRAMMING 101 
by Al Stevens 

Al reports on what it’s like to go on tour with a world-famous author like the 
legendary Herb Schildt. 


JAVA Q&A 107 


by Krishnan kangaraajan 

There are a number of ways to test Java classes. Our author examines 
conventional techniques, then presents an alternate approach that he feels is 
superior in many ways. 


ALGORITHM ALLEY 115 


by Ron Gutman 

B-Tree databases are very efficient with one-dimensional data. Ron shows how 
Hilbert curves can be used to efficiently manage multidimensional data, with 
no changes to the underlying database. 


DR. ECCO’S OMNIHEURIST CORNER 123 


by Dennis E. Shasha 
Ecco and Liane are challenged by the Borghese Club to win the game of “Flats 
and Steeps,” which is based on the principles of columns and beams. 


PROGRAMMER’S BOOKSHELF 127 


by Jeff Taylor 
The focus of Jeff’s review this month is Linux Network Administrator's Guide, 
by Olaf Kirch. 
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RESOURCE CENTER 


As a service to our readers, source code and 
related files, and author guidelines are available 
at http://www.ddj.com/. Source code is also 
available via anonymous FTP from ftp.ddj.com 
(199.125.85.76). Letters to the editor, article 
proposals/submissions, and inquiries can be sent 
to editors@ddj.com, faxed to 650-358-9749, or 
mailed to Dr. Dobb’s Journal, 411 Borel Ave., 
Suite 100, San Mateo, CA 94402-3522. 

For subscription questions, change of address, 
and orders, call 800-456-1215 (U.S. or Canada). 
For all other countries, call 303-678-8475 or fax 
303-661-1181. E-mail subscription questions to 
ddj@neodata.com or write to Dr. Dobb’s Journal, 
P.O. Box 56188, Boulder, CO 80322-6188. 

Back issues may be purchased for $9.00 per 
copy (includes shipping and handling). For issue 
availability, send e-mail to orders@mfi.com, fax 
to 785-841-2624, or call 800-444-4881 (U.S. and 
Canada) or 785-838-7500 (all other countries). 
Back issue orders must be prepaid. Please send 
payment to Dr. Dobb’s Journal, 1001 W. 23rd 
Street, Suite 200, Lawrence, KS 66046-2700. 

Individual back articles may be purchased 
electronically at http://www.ddj.com/ as ZIP 
archives. 


NEXT MONTH 


The “eyes” have it next month, when we 


examine the latest in visual programming 
tools and techniques. 





Real-world data management solutions 
are typically more complex when one 
examines the pieces, than initially 
recognized by the majority of database 
programers. All software projects are 
complex puzzles comprised of many 


details, most of which are data-related. 


Often today’s “DBMS” solutions sacrifice 
the speed or control essential for a 


competitive application. 


c-tree Plus®, by FairCom, has been the 
choice of commercial developers for twenty 
years precisely because it offers the 
flexibility and control at the detail level to fit 
a wide variety of data management needs. 
Proven on large Unix servers and 


workstations, c-tree Plus’s small footprint 
and exceptional performance have also made 


it the engine of choice for professional 


developers on Windows and Mac. c-tree Plus 
offers sophisticated ISAM level control with 
which the developer may define precise data 
management solutions, making it a perfect 
fit for any development project requiring 
specific data handling features. 


c-tree Plus® offers the most 


mature ISAM solution today... 


FairCom’s 
c-tree Plus 
database 
engine: 


e Advanced Indexing 
Technology 

¢« Complete Source Code 

¢ Complete Transaction 
Processing 

* ODBC Interface 

¢ Over 25 Developer’s 
Servers Included 

° Portable Multi-threaded 
API 

¢ Royalty Free 

e Standalone, Multi-user or 
Client/Server Models 

e Thread-Safe Libraries 

¢ Y2K Compliant 





Don’t wait, see for yourself! 


The FairCom 
Server: 


A solid, high performance 
database server that is 
scalable, portable and offers 
unequalled control. FairCom 
has been providing database 
solutions to the commercial 
development community for 
twenty years. You won’t find 
a better solution, with these 
features and performance 
anywhere else! 

e Client Side Source Code 
e File Encryption 

¢ File Mirroring Logic 

* Full Conditional 

Index Support 
° Full Heterogeneous 

Networking 
¢ Multiple Communication 

Protocols 
¢ Online Data Backup 
¢ Small Memory Footprint 
° Flexible OEM 

Licensing Options 
° Source Code Availability 


USA. 800.234.8180 E 





Other company, 





Database SOLUT eo 


Phone: USA 573.445.6833 - EUROPE +39.035.773.464 
product and operating platform names are re 


All these 
platforms 
supported in one 
package: 


MIPS ABI, DEC Alpha, Sun 
SPARC, Windows 9X, SCO, 
SS8OPEN, AIX, RS/6000, 
HP9000, Sun OS, 
Interactive Unix, Linux 
(Alpha...), AT&T System V, 
QNX, Free BSD, OS/2, 
Mac, Windows NT, 
Windows 3.1, DOS, 
Netware NLM, & Banyan 
VINES. 

















since 1979 


04 - BRAZIL +55.11.3872.9802 


arks of their respective owners. 








SOFWARE 
I. ) "Ghia TOOLS FOR THE 
é PROFESSIONAL 
LO 8 Na es Pim | PROGRAMMER 


PUBLISHER 
Timothy Trickett 


EDITORIAL 

EDITOR-IN-CHIEF 

Jonathan Erickson 

MANAGING EDITOR 

Deirdre Blake 

MANAGING EDITOR, DIGITAL MEDIA 
Kevin Carlson 

SENIOR TECHNICAL EDITOR 

Tim Kientzle 

TECHNICAL EDITOR 

Eugene Eric Kim 

SENIOR PRODUCTION EDITOR 
Monica E. Berg 

EDITORIAL ASSISTANT 

Amy Lincicum 

ART DIRECTOR 

Margaret A. Anderson 

INTERNET BROADCAST PRODUCER 
Philippe Lourier 

CONTRIBUTING EDITORS 

Al Stevens, Tom Genereaux, David Betz, Bruce Schneier, 
Mark Russinovich, Bryce Cogswell, Ray Duncan, 
Jack Woebr, Jon Bentley, Dennis Shasha 
EDITOR-AT-LARGE 

Michael Swaine 

PRODUCTION MANAGER 

Denise Denis 


CIRCULATION 

DIRECTOR OF CIRCULATION 
Jerry Okabe 

GROUP CIRCULATION MANAGER 
Michael Poplardo 


MARKETING/ADVERTISING 

SALES DIRECTOR, EAST 

Brenner Fuller 

SALES DIRECTOR, WEST 

Paul Miller 

MARKETING DIRECTOR 

Holly Vessichelli 

DIGITAL MEDIA MANAGER 

Michael Calderon 

MARKETING ASSISTANT 

Marquita Tinio 

ACCOUNT MANAGERS see page 129 

Stan Barnes, David Katch, Gabriel Rogol, 
Michael Beasley, Tom Hudner, Brenner Fuller, 
Michael Kelleher, Linda Guyette, Keith Johnson, 
Elizabeth Doherty, Stacey Mochizuki 
GRAPHIC DESIGNER 

Carey Perez 





DR. DOBB'S JOURNAL 
411 Borel Avenue, San Mateo, CA 94402-3522 
650-358-9500. http://www.ddj.com/ 


MILLER FREEMAN INC. 
CEO/MILLER FREEMAN WORLDWIDE 
Tony Tillin 

CHAIRMAN/MILLER FREEMAN INC. 
Marshall W. Freeman 

PRESIDENT 

Donald A. Pazour 

EXECUTIVE VICE PRESIDENTS 

H. Ted Babr, Darrell Denny, Galen A. Poss, 
kegina Starr Ridley, Ed Pinedo 

SENIOR VICE PRESIDENTS 

Wini D. Ragus, Peter Hutchinson, John Pearson 
VICE PRESIDENT/PRODUCTION 

Andrew A. Mickus 

VICE PRESIDENT/CIRCULATION 

Jerry Okabe 

VICE PRESIDENT/GROUP PUBLISHER 
Peter Westerman 


Estimated print run 165,000. 


Un Miller Freeman 


A United News & Media company 





P Printed in the 


American Buisness Press USA 


WBPA 
Dr. Dobb’s Journal, July 1999 





C++ components from Rogue Wave: the choice of champions! 


I. can be a stretch to create portable, scalable apps and deliver them on time. And Save the day! 
building and testing your own low-level C++ components can really put your game at risk. VY Fundamental classes 
Why not let Rogue Wave help you cover all the bases? With the integrated and reusable classes Y Networking classes 

in Tools.h++ Professional, Threads.h++, and Standard C++ Library, your development team can ¥Y Multithreading classes 


get a head start on building a solid, high-performance foundation for every application. Know v Solutions for Java/C++ 


the score: use C++ components from Rogue Wave, and your whole team will be batting 1000! interoperability 


Get the stats. Download your free demos and white papers now at: 
www.roguewave.com/ad/catch 


ri Rogue Wa 


SOFTWARE 
Components Without Limits 





Rogue Wave: 800-487-3217 * D.A.CH.:+49-6103-59 34-0 » UK: +44-118-988 0224 
France: +33-1-4196 2626 * Italy: +39-02-3809 3288 * Rest of Europe: +31-20-301 26 26 


Rogue Wave and .h++ are registered trademarks of Rogue Wave Software, Inc. All other trademarks are the property of their respective holders. 
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EDITORIAL 


quantity of both. What with retirees stretching house joes, students hunched over laptops, 

body-pierced tattooed generation-whatevers chugging cappuccinos, and yuppies double- 
parking SUVs to dash in for decaf lattes with skim milk and Sweet’N Low, it’s easy enough for a 
caffeine-stoked, fly-on-the-wall editor like Yours Truly to pick up on everything from world 
affairs to new silverware. Here’s a recent sampling: 

At one table, NT versus Linux was the flame du jour, specifically, the recent NT/Linux shootout 
conducted by benchmarking firm Mindcraft (http://www.mindcraft.com/). Not only did Microsoft 
pay for the comparison, but the tests reportedly took place in a Microsoft lab with the assistance 
of at least one Microsoft contractor. Take a guess on the results. When the results were published, 
the uproar was such that Mindcraft decided it might be a good idea to rerun the tests. Not good 
enough, said Linux insiders Alan Cox, Bob Young, and Linus Torvalds, since the tests were 
designed from the git-go to highlight NT’s strengths. Furthermore, Linux experts weren’t allowed 
onto the testing site, while presumably NT experts were. By the time you read this, a third cycle 
of benchmarks supposedly will have been run. 

Back in the corner, the definition differed on what exactly constitutes a “compelling app.” For 
some, it is simply a program you've just got to have. For others, it’s software for which you are 
willing to mortgage the house, chuck your day job, and trust your future to. In this sense, a lot of 
the pen-based computer applications of the early 90s come to mind. Today’s “compelling” apps 
are, in general, being defined by the Internet and, in particular, by online services such as auctions, 
such as eBay (http://www.ebay.com/) and investments, like E*Trade (http://www.etrade.com/). If 
statistics are to be believed, a lot of people have bet their back 40 on these forms of e-commerce. 
eBay, for instance, claims that 80 percent of its hundreds of thousands of transactions are being 
made by 20 percent of its users— entrepreneurs who are making their living working full-time at 
eBay-based businesses. You have to assume that E*Trade has spawned similar numbers. 

Then there were the college professors grousing about recent assaults on Freedom of Speech 
and the principle of academic independence. At issue was a guest editorial in The Kansas City 
Star—written by a University of Missouri-Kansas City law professor—which criticized the 
Missouri legislature for consistently making mistakes when writing laws. In retaliation, Stalin- 
wannabes in the House, led by a Rep. Dennis Bonner, proceeded to “send a message” to critics 
by stripping nearly $3 million from the university’s budget— even though the professor wrote the 
editorial as a private citizen. These bozos in legislative clothing then cheered when the measure 
passed. Unable to rein in his stupidity, Bonner went on to send letters to the legislature in the 
neighboring state of Kansas, urging it to cut funds for the city in which the law professor resides 
and serves on the city council. Thankfully for the citizens of Missouri, the state Senate stepped in 
to restore sanity and funding. In the end, the only thing these unAmerican legislators in the Show- 
Me state showed is a new definition of petty brainlessness. 

It was during this kind of give and take that a sleepy-eyed Dr. Dobb’s reader (well, it was a 
little after noon) stumbled over to my table and said “Hey, if you guys at DD/ are so smart, why 
don’t you have a list server?”. For once I had a ready answer—‘“We do,” I replied. Yes, we've set 
up a list server that lets us periodically send e-mail announcing new projects and features. To 
subscribe to the list, go to http://www.ddj.com/maillists/ and complete the online form. 

Emboldened, this same reader, who makes his living programming 60 hours a week, then 
proceeded to express irritation with Howard Rubin (http://www.hrubin.com/), a professor of 
computer science at the City University of New York and a research fellow with the META Group 
(http://www.metagroup.com/), and his recent “IT Trends ’99” report that suggested U.S. 
programmers are less productive but more expensive than programmers elsewhere. Using the metric 
of average number of lines coded per year, U.S. programmers are coding at the rate of 7700 lines, 
while developers outside the U'S. are sailing along at the rate of 16,700 lines annually. Since I haven’t 
read the complete report, I'll withhold comment for now. However, based on a speech Rubin 
presented at a DD event last year, there’s a lot more involved than what recently made the headlines. 
If I recall Rubin’s 1998 comments correctly, for instance, Canadian programmers outstripped U.S. 
programmers in the total number of lines, but also introduced more errors. In short, Rubin said, U.S. 
programmers led the way when the metric includes more factors than just raw code. 

My new friend was less forgiving, however, and since we promote family values here, I’ll 
hold off his exact words. Let’s just attribute his grumpiness to not yet having that first cup of 


coffee for the day. 


Jonathan Erickson 
editor-in-chief 
jerickson@ddj.com 


T he beauty of the Java Dive isn’t just in the quality of its coffee or conversation— it’s the 
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This remarkably simple idea is now Simple? Yes. And effective. 
connecting the world’s software. 


Accommodating standards also opens the door to 


Only Voyager Application Server™ saves you unparalleled integrating emerging technologies like Jini™ and 
time and lowers cost by allowing Enterprise JavaBeans™ Universal Plug 'n Play. So you're geared for the future — 
to send and receive messages from multiple ORB while protecting today's development investments. 


standards including CORBA, RMI, and soon, DCOM. 
The Universal Container™ fits right in with other ground- 
Which means any EJB becomes instantly accessible to any breaking features we've implemented. Like packaging 
object or component on any machine anywhere. complex EJB code with a click on our intuitive graphical 
interface. Or, auto-synchronizing between modified code 
and previously packaged components. 








The Universal Container” 





VOYAGER 





You also get robust transactions. Security. Advanced 
manageability. Dynamic XML™. Plus, Voyager ORB 
Professional™ with its universal communications 
architecture, dynamic proxy generation, mobile 
autonomous agents, Dynamic Aggregation™ 


and much more. | A | E [ T)}S P f [ [ 


Discover the unique power of universal containers. 
And other remarkable Voyager™ breakthroughs to Connecting the world with real Java, real solutions. 


connect your world — now. 






Visit www.objectspace.com/go/universal. 
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Computer History 

Dear DDJ, 

Thank you very much for the writeup 
about our IBM 1620 restoration work 
which appeared in “News & Views,” DDJ, 
February 1999. The generous response 
from DDJ readers has been surprising. 

So far, I've received e-mail offering a 1311 
disk drive, some spare parts, a few manu- 
als, some software, and a number of per- 
sonal accounts of the machine. We're still 
looking for peripherals, especially a 1622 
card reader/punch, a 1621/1624 paper tape 
reader/punch, and a 1443 line printer. 

I have one piece of sad news to report. 
Joe Crespo, the IBM 1620 development en- 
gineer heading the restoration effort, died 
tragically since the article was written. We 
are continuing with the restoration in Joe’s 
memory but could use some technical ad- 
vice from any IBM 1620 engineers or field 
engineers who worked on the machine. 

Finally, the restoration team is also de- 
veloping an extensive “IBM 1620 History 
Site” that readers might enjoy (http://www 
.computerhistory.org/IBM1620/). 

Dave Babcock 

daveb@sgi.com 


Motion-Tracking Devices 
Dear DDJ, 
Thank you for your article “Controlling 
Motion-Tracking Devices,” by Mike Har- 
rington (DDJ, March 1999). I have been in 
this field for 19 years, and Harrington did 
a good job of explaining the real-time prob- 
lems facing VR users of motion trackers. 
A motion tracker spewing data continu- 
ously at 47 characters every 16 milliseconds, 
can quickly bring a host to its knees if the 
serial port driver was written for 10 char- 
acters per second from a human typist. 
Motion tracking is one area where vast- 
ly different technologies compete, as ev- 
ery technology has serious drawbacks: 
Magnetic trackers are disturbed by near- 
by metal, ultrasonic and optical trackers 
need clear lines of sight, inertial trackers 
drift with time, tilt sensors can’t distinguish 
orientation from position accelerations. 
One gotcha in VR trackers is failing to 
do dynamic testing early. Final integration 
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is a bad time to find out that your tracker 
can’t track both accurately and quickly. 

My favorite company killer is the tilt sen- 
sor for orientation tracking: It appears to 
be simple and gives two degrees of free- 
dom of angular measurement, typically el- 
evation and roll. When paired with a mag- 
netic compass, azimuth is also obtained. 
Thus, you have a simple 3DOF tracker. 

However, the tilt sensor does not work 
well dynamically. The tilt sensor gives the 
direction of the total acceleration. In the 
static case, that is the earth’s gravity. In a 
dynamic case, position acceleration adds 
to the earth’s gravity, shifting the direction 
of total acceleration. 

Wear a tilt-sensor VR helmet, and move 
your head forward and backward, without 
tilting your head, and watch the virtual 
world jump up and down in elevation. 

Analog Devices points out that ac- 
celerometers solve this problem, as the mag- 
nitude of the acceleration is then known, 
permitting corrections to be calculated. 

Peter T. Anderson 

traneus@emba.uvm.edu 


Asleep at the Keyboard? 
Dear DDJ, 
Aside from its obvious intrinsic scientific in- 
terest, one can imagine that only a sense 
of guilt, one engendered by the rarity of 
DD} articles that mention Fortran, motivat- 
ed you to publish “Simulating Severe Weath- 
er,” by Louis J. Wicker in the March 1999 
issue. What else, in heaven’s name, could 
have prompted you to relinquish precious 
space to an article that doesn’t discuss C++ 
or Java? Perhaps the DD/ computer language 
police were asleep at their keyboards? 
While not quite as egregious as an ar- 
ticle discussing Cobol, one that mentions 
Fortran exclusively merits the condemna- 
tion of any worthy programmer, regard- 
less of any other redeeming qualities. One 
can only hope that the editors of DD/ are 
not implying that serious programmers ac- 
tually use Fortran, or even Fortran 95. Cer- 
tainly you've thought of the repercussions 
if standardized, simple, elegant, easily un- 
derstood languages like it or Ada, ones 
that are easily parallelized and generate 
compact, fast-running programs were to 
be adopted on a broad scale. Regular 
readers of your magazine surely expect 
you to place the highest priority on the 
job security of the vast coding armies of 
C++ and Java programmers and on their 
continued high renumeration. The same 
can be said for the continued existence of 
the mammoth support industry that pro- 
duces the tools that allow them to ferret 
out their programming errors. These read- 
ers do not expect you to drive to the ranks 
of the unemployed the legions of authors 
of thousand plus page tomes on these two 





languages that weight heavily on leagues 
of shelf space in your typical bookstore. 
Furthermore, there must be no small de- 
gree of self interest to consider: the con- 
tinued livelihood of the cadres of writers 
who wile away their years dissecting these 
cryptic, endlessly changing languages with 
the talmudic precision they demand. 

I speak only for myself, but I think per- 
haps I echo the sentiments of many, when 
I ask for a restoration of sanity to the ed- 
itorial staff of DDJ. 

Norman S. Clerman 

opcon@cinti.net 


Mindstorms 

Dear DDJ, 

Thanks to Jonathan Erickson in his April 
1999 “Editorial” for legitimizing the desire 
for grown men and women to play with 
Lego. The Mindstorms kit is the first toy 
in years that I really wanted for Christmas, 
and my kids (and understanding spouse) 
got one for me! 

Needless to say, the first thing I asked 
to myself was, “Can I program this thing 
in FORTH?” After looking at the Web for 
resources I came up with legOS and a de- 
tailed description of the firmware by 
Kekoa Proudfoot. 

I wrote a FORTH interpreter for the lit- 
tle yellow box in about 40 hours, the re- 
sults and lots of references to online LEGO 
Mindstorms resources are at http://www 
.bmts.com/~rhempel/lego/pbFORTH/de- 
fault.html. There is a huge community of 
adults that I believe Lego sorely miscalcu- 
lated in their production estimates, and we 
are all happy to share our work. 

Ralph Hempel 

rhempel@bmts.com 


Dear DDJ, 
In regard to Jonathan Erickson’s April 1999 
“Editorial,” I first heard about the Lego Mind- 
storms Robot last summer and have not 
come down yet! I got mine for Christmas 
and haven't stopped playing with it. It is the 
most interesting and educational gizmo I 
have seen. I am trying to build the cat and 
mouse robot but like you, I have to wait 
for school to let out to ask the “experts.” 
I'm not a programmer but the language is 
easy for anybody. Anybody mention Java 
for the Mindstorms robot? Thanks for the 
tip on do it yourself sensors. My browser 
is open and I’m ready to rock. 

Steve Grappone 

steve. grappone@insignia.com 


Java Jive 
Dear DDJ, 
Like Al Stevens in his April 1999 “C Pro- 
gramming” column, my in-laws live in a 
dead spot too. My stair steps hover around 
1 or 2 and I have to go out to the driveway 
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‘up for days as you run test cases through your application. You need J’ 





J” is the world's first automatic white-box module testing tool for Java. With a single click, jtest! finds 
your undocumented, uncaught runtime exceptions. Unlike most Java products, J°°* also checks your 
internal code structure for weaknesses and monitors code coverage to ensure complete testing. 


Serious programmers and corporations are using J” on all of their Java code. Join them, and find out 
how easy it is to produce code that is clear, concise, and easy to maintain! 
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[Fey ite Jiest is SO easy to use, you can start finding bugs 


automatically at the click of a button. 


fig Source Viewer When Jiest finds an 
40=) LUO) MESTALONAVSINYLOLE 
the exact code responsible 
for the exception, making 
bug-fixing fast and pain- 


less. 
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With Jiest!, it’s easy to focus on the 
exceptions that are most important to you. 
You can customize reports to suppress 
exceptions by type, name, 
and enclosing method. 





“test! is a tool I want to add to my arsenal”. 


_ Luke Cassidy-Dorion, 
_ Java Pro, February 1999 
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(continued from page 12) 

as well. I haven’t told them yet. I figure 
living in ignorance is better than living in 
denial. Anyhow, I liked his comments re- 
garding Java. I’m a full-time Java devel- 
oper and I really am annoyed with all the 
hyperbole that hovers around Java. As an 
object-oriented programming language, 
Java is really nice. With a bit more evo- 
lution, I expect it to become much more 
popular for the right reasons. 

Java right now is too boutique’ish. It’s 
a cute little language that hasn’t got valid 
acceptance. 

Other issues that remain undiscussed 
concern the need for platform indepen- 
dence. What if I just want an alternative 
from C++/MFC? Symantec’s Visual Café 
(and perhaps others) has a feature to 
compile Java applications into an exe- 
cutable. 

That’s really what people want. Use 
Windows as the operating system but have 
an alternative to C++/MFC. 

Jim Cloughley 

James_Cloughley@markham.longview.ca 


Dear DDJ, 

In his April 1999 column entitled “Java Jive,” 
Al Stevens described his problems with cel- 
lular phones. His cell phone problem may 


be due to the fact that he has a digital 
phone. This is still relatively new and 
does not have the infrastructure of the 
analog phone market. He might ask 
AT&T for a map of their coverage areas. 
Chances are that Al is on the edge of 
one of their areas. 

Also, Al made a valid point about the 
over-hype of Java. I am a Java program- 
mer and while there are some great ar- 
guments for the language, I don’t think it 
the answer to all of the world’s problems. 

However, from his column, it would 
seem that he wants to say that we will 
never do without some other base OS 
(Windows, Linux, and so on). I disagree. 
There are movements to incorporate a 
Java-based OS (http://www.jos.org/). It’s 
not hard to imagine a computer of any 
kind that loads the JVM into memory 
from BIOS on startup, then executes a 
startup sequence of something like JOS. 
He could even have something minimal 
in small devices like cell phones and large 
graphical Java-based OS comparable to 
Windows with Java-based word proces- 
sors and browsers and what have you. 
By implementing the VM in the hardware, 
it might actually be fast enough to run. 

Kevin Johnson 

kevin@utig.ig.utexas.edu 


Analyzing Algorithms 
Dear DDJ, 
I read with interest Jon Bentley’s “Analy- 
sis of Algorithms” (DD/, April 1999). I 
heeded Jon’s suggestion to study the sub- 
tleties of Search1 (algorithm 1) before pro- 
ceeding. What I noticed immediately (and 
I’m sure I’m not alone) is that the first it- 
eration of the For loop is wasteful, be- 
cause at that point i==(m-1), so that the 
parameters to the swap() function are 
identical, meaning a vector gets swap(Jed 
with itself. Eliminating all these extrane- 
ous iterations would do a lot to improve 
this algorithm, and subsequent ones. 
John Bartley 
bz910@freenet.buffalo.edu 


The CVS Data Format URL 
Dear DDJ, 
Thanks for publishing my article “The CVS 
Data Format” (DDJ, May 1999). However, 
I've received dozens of e-mail messages 
from readers asking about the URL of our 
web site. Apparently a “-” was dropped. 
The correct URL is http://www-gtarpa 
.USC.ES. 
Cesar A. Gonzalez Perez 
phcgon@usc.es 


DDJ 









IMAGE FILE FORMATS 
IMPORT/EXPORT 

JPEG GIF* 

-Lossy DICOM 

-Lossless CALS 
MPEG WAN 
JBIG WPG 
PNG WMF 
PSD EMF 
PCD AVI 
EXF MSP 
FPX RLE 
EPS PNM “a 
IOCA PBM nee 
MODCA 
ce POM = IMAGE PROCESSING 
CUR TIFF 6.0 TRANSFORMS 
is acti FILTERS 
IMG ie DRAWING 
DIB ieee REGION OF INTEREST 
FAX -RLE COLOR CONVERSION 

-LZW 

MAC COT SCANNING / CAPTURE 
TGA -CCITT G31D 
RAS CCITT G32D DISPLAY & SPECIAL EFFECTS 
PCT <CcirT 
cue pe ANNOTATIONS 
BMP -Palletized 
OS/2 BMP pines COMPRESSION 


-Bitonal 
-CMYK 
-YCbCr 
-CIELAB 





800-637-1837 


30-DAY MONEY BACK GUARANTEE 
FREE TECHNICAL SUPPORT 


“License required from Unisys for formats using LZW compression. LEAD and LEADTOOLS are registered trademarks of LEAD Technologies, Inc. All other product names are trademarks of their respective owners. 





The leaders in software development choose award-winning 
LEADTOOLS imaging technology - companies like Microsoft, 
Hewlett Packard, Intel, Boeing, Xerox and thousands of 
others use LEADTOOLS in their high volume applications and 
internal systems. Why? LEADTOOLS gives developers the 
most flexible and powerful, imaging technology available. 
Take a quick look at what LEADTOOLS offers. 
detailed descriptions, visit our website, www.leadtools.com! 


For more 


IMAGING COMMON DIALOG M 


INTERNET/INTRANET 
DATABASE 
OCR 


SCREEN CAPTURE 
PRINTING 
AUDIO/VIDEO 
MEDICAL 
VECTOR 


www.LEADTOOLS.com 
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HASP® Helps You Break 
Sales Records 


The Winning Advantage is that HASP actually creates new sales 
opportunities while providing you with unparalleled security. 









HASP’s Remote Update System makes it possible for you to 
remotely modify the execution of software modules. For 
example, you can easily transform a demo into a fully 

licensed version or you can grant extra licenses to a 
network application. 










HASP enables all kinds of exciting new sales strate- 
gies: module sales, in-the-field upgrades, try-before- 
you-buy, enhanced licensing capabilities plus run- 
or time-limited product use demos. Since HASP 
produces 100% user registration, you can sell 
more upgrades and add-on products too. 


HASP protects software. And HASP helps 
sell it. Is it any wonder twenty-five 
thousand winning software developers 
depend on HASP? 


Call and order your Developer's 
Kit today! 
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North America Aladdin Knowledge Systems Inc. Chicago Tel: +1-800 562-2543, +1-847 808-0300, International +972-3-636-2222 
_ New York Tel: +1-800 223-4277, +1-212 564-5678, | Email: hardlock.sales@hardlock.com Email: hasp.sales@aks.com 


Email: hasp.sales@us.aks.com HASP is a registered trademark of Aladdin Knowledge Systems, Ltd. 





by FarPoint Technologies 
Use FarPoint’s Spread 3 to create 
powerful database front-ends, manage 
the display and entry of two billion items 
using the enhanced Virtual Mode, print 
reports using Print Preview, perform 
calculations, import/export Excel 97 files 
(32-bit versions), export HTML files (32-bit 
versions), sort data, support OLE Drag 
and Drop, or take advantage of its 
unparalleled cell-level formatting, 
including twelve built-in cell types. 
Unmatched power, flexibility, and speed 
combine to make Spread the perfect 
component for any application. 
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by Informatics 
© Supports all major bar code symbologies. 


Optional support for new 2D symbols 
(e.g. PDF417, MaxiCode, DataMatrix) 


e Render spec compliant bar codes to any 
device context 


e Two Activex controls fully support 
Drawing and Font DLLs and can be 
bound to a database. 

Exclusive Offer. FREE Wasp Bar Code 
Scanner ($175 value) w/purchase. 
Paradise No. 
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ActiveX & DLL Plus 2D 








by Wise Solutions 


Wise Solutions introduces 

a new generation of 

versatile installation suites 

for a wide range of Lane ao 
developer needs with new features and enhancements that 
make installation scripting, patching, repackaging, and Web 
deployment a snap. 


InstallBuilder 
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by Faircom 


DOS ¢ WINDOWS ¢ NT e UNIX 

e 0S/2 © SUN © RS6000 © HP9000 

e MAC e¢ ONX @ LINUX @ SCO. 

This well known, highly-portable 

data management package has become 
established as the tool of choice for 
commercial development. Offering 
unprecedented data control, choose from 
direct low level access, ISAM level, or ODBC 
access with the FairCom Server. Single User, 
Multi User, or optional Client/Server, ANS! 
Standard. Full Source. 
No Royalties. 


Paradise No. 
F01 0120-FN 


*835.” 


Supports 25 0/S! 


by LEAD Technologies, Inc. 


LEADTOOLS is a family of 
comprehensive toolkits designed 

to help programmers integrate 
color, grayscale, document, 
medical, multimedia and vector 
imaging into their applications 
quickly and easily. Whatever your 
programming needs, LEAD has a 
toolkit specifically designed to 

give you the best imaging 
technology available with the stability 
and dependability you would expect 
from the imaging LEADer. 
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by Premia 

New in CodeWright 6.0, the #1 selling 

programmer's editing system for the 

Windows platform: 

e CodeSense—word completion and 
function parameter help 

¢ CodeFolio—work faster by giving your 
teams a shared view of your most 
commonly used code 

e Sync Technology support for Visual Basic 
6.0 and Borland Delphi 4 


e Bi-directional synchronization for Visual 
Studio 97 and 98. 
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by Seapine Software 


TestIrack is the fastest and 
most complete multi-user 
bug tracking solution for 
Windows 95/NT. Tracks bug 
and feature requests, customers, users, test configurations, and 
more. Advanced features include e-mail notifications, e-mail bug 
import, duplicate bug handling, release note generation, and 
much more. Distribute TestTrack’s standalone bug reporter to 
your customers to automate customer 
Support. With all of its power, TestTrack 
remains the easiest bug tracking solution 
to use and maintain. 


Testi lta 


_Simply Better Bug Tracking 
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by Intel 


The comprehensive solution for 
developers of high performance bs 
software for the Intel Pentium® Ill | | "he 
processor—from the people who . ] 
designed it. 


Intel offers the VTune™ Performance 
Enhancement Environment 4.0, a 
software performance solution for 

the Pentium® III processor, which offers 
a set of tools to help you analyze and 
improve the performance of your 
software for the Intel Architecture. 


VTune- 
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by Rational Software 


Rational Visual Test 6.0 delivers new 
levels of productivity and power for 
developers and testers deploying 
mission-critical applications on 
Windows 95/NT or the Web. 

Rapidly create tests for applications 
of virtually any size, created with any 
development tool. 


Features and Benefits 

e Web testing (HTML/DHTML) 

e Tight Integration with 
Microsoft Visual Studio 6 

e Active Accessibility Support. 


Rational Visual Test 
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by FarPoint Technologies 


Easily create professional data-entry 
screens using Input Pro’s eight custom 
controls. Input Pro's formatted-edit 
controls automatically validate 
date/time, numeric or text data 
entered by your user, database or as FARPOWT's 
the application programmatically Input Pro 
assigns or edits values. Use the 
boolean control to display a custom 
true/false/grayed value appearance. 
Use the memo control to display large 
amounts of text, even those greater 
than 64K. 
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Visual SlickEdit RoboHELP’® Office 


by Blue Sky® Software 

RoboHELP Office—tThe Industry 

Standard in Help Authoring 

RoboHELP Office is the #1 best-selling 

Help authoring solution. Use RoboHELP 

to create full-featured, professional Help 

and documentation systems. 

e Create cross-platform Help and convert 
existing files to .HLP 

e Generate electronic and printed documentation 

e Features world-class HTML editor, 

optimized for HTML Help 

Winner of “Programmer's Paradise 

Riding the Crest Award” for Best-Selling 

Help Authoring Software. 


DevIrack 3.0 
by TechExcel 















by MicroEdge, Inc. 
Visual Slickedit® v4.0, the award-winning 
editor from MicroEdge, Inc. increases 
development productivity, and improves 
software quality. It supports most 
languages out of the box and is extendible 
to support your favorite language as well. 
With a multi-platform presence and inte- 
gration with industry leading development 
environments, Visual SlickEdit provides an entire 
organization with a standard coding environment. 
Powertul features include: Context Tagging”. 
Dynamic Difference Editing”; FTP Support; A Class 
Browser; Dynamic Tagging and a Code Beautifier! 
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by InstallShield 
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Software Corp. DevTrack is the premier defect- and 

install Shiold® Prafessionalisthe P. project-tracking tool designed specifically 

commercial developer's choice for - for software development teams. DevTrack 

creating industry-standard Microsoft® a comprehensively tracks and manages all 

Windows® application installations € defect information, feature requests, and 

Critically acclaimed and used by aval development issues. Intuitive and powerful, 

ninety of the top 100 independent InstallShield5.5 | | DevTrack provides an integrated client/ 

software vendors, InstallShield EE | | server and intranet/Internet solution for 

Bcafsecional afers both scripting — enterprise project management. DevTrack } 
power and timesaving visual tools in an Paradise No. lee stele se ee MS Visual Paradise No. 
integrated development environment. 121 0330-FN ee T34 0130-FN 


architecture, e-mail notification, extensive 
customization, and presentation-quality 
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SourceOffSite Pro Ed. 2.0 L 


by SourceOffSite, Inc. 


Access SourceSafe” 

over the Internet 

Connect to a centralized Visual 
SourceSafe database using any 
standard TCP/IP connection. 

¢ |DE integration 

e Over 10 times faster than RAS 
e Efficient—uses data compression 
e Secure—up to 128-bit data encryption 
e 

e 








The choice for intricate application 
requirements is InstallShield Professional. 


$749." 











by Elsinore Technologies 


The only suite of project-oriented 
enterprise bug-tracking tools for 
Microsoft developers. 


Complete integration with Visual 
Studio—track you bugs without 
leaving your IDE! 


VBA-enabled for complete customization! 
Status promotion model for controlling 
workflow. Integration with Visual 
SourceSafe, PVCS, ClearCase and 
other SCC systems. Web-based interfaces 
to Visual Intercept are also available! 
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Paul Bunyan Message Logger 


Familiar—the look and feel of VSS 
Cross-Platform—98/NT/UNIX. 
tt Pro edition 1 users. 








True DBGrid Pro 6.0 


by APEX Software Corp. 


The World’s Most Popular 

Grid just got better... Again! 

New 6.0 features include: Native 
support for ADO and OLE DB (including 
master-detail and hierarchical data 
sources); Multi-column sorting with an 
enhanced XArray object; OLE drag and 
drop; Merge cells; Full support for IE 

and ActiveX compatible browsers; Export 
to HTML; Enhanced styles for displaying 
in-cell graphics (including background and 
transparent bitmaps); Formatted preview 
and printing; and much more! 





by Levon’s Wake 


Paul Bunyan is the 
absolute state of the 
art message logging 
system! Features include: 
remote message retrieval 
over the Internet; support 
for C/++, VB, and others; 
lightning speed; and 
much more. Professional 
and Enterprise Edition 
also available. 
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Microsoft Office 2000 


Developer Edition 
by Microsoft Corporation 
All the essential tools for building 


and deploying solutions with 
Microsoft Office 2000 


Microsoft Office 2000 Developer includes 
Microsoft Office 2000 Premium and developer 
tools for building, deploying, and managing 
Office 2000 solutions with data and the Web. 





t Price after manufacturer's $40 mail-in rebate. 
** For owners of Office 2000 (or a Visual Basic for Applications 
(VBA) 6.0 enabled host application) and want the tools in 
Office Developer 2000. 
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eGear®99: 


Building powerful 


imaging solutions is now 
as easy as Child’s play 


The most powerful imaging toolkit now offers 
several new Plug-Ins with support for 

10 CAD/Vector formats, high-speed 
ISIS® scanning, OCR, Barcodes 


and more. 


100+ Formats! 





Standard Formats 

AFX, Animated GIF, ASCII, ATT, 
AVI, BMP, BRK, CALS, CCITT 
Group 3-2D, CCITT Group Ill, 


CCITT Group IV, CLP, CUT, DCX, 


DIB, EPS*, EXIF, FlashPix, GIF, 


GX2, ICO, IFF/ILBM, IGF, IMARA, 


IMG-Xerox, IMG-GEM, IMT, 
IOCA, JFIF, JPEG, KFX, Lossless 
JPEG, LV, MAC, MO:DCA, MSP, 
NCR, OS/2 Bitmap, PBM, PCD, 
PCX, PGM, PICT*, PNG, PNM, 
PPM, Progressive JPEG, PSD, 
RAS, RLE, SGI, SUN, TGA, TIFF, 
Transparent GIF, Winfax, WMF, 
WPG*, XBM, XPM, XWD 


Special Options: 
DICOM, ABIC, JBIG, Wavelets... 


*Raster only. 
License required from Unisys for formats 
using LZW compression. 


NEW! CAD/Vector Plug-In: 
DWG, DXF, DGN, HPGL, CGM, 
HPGL/2, ME10, DRW, RIS, PICT 


NEW! Raster Plus Plug-In: 


30 extra raster formats 


SIS 


scanning | 








© AccuSoft Corporation. All Rights Reserved. 
AccuSoft and imageGear are registered trademarks 


of AccuSoft Corporation. High Performance Imaging 
and NetVue are trademarks of AccuSoft Corporation. 


All company and brand names are trademarks 
or registered trademarks of their owners. 


ISIS is a registered trademark of Pixel Transiations, 
a division of Input Software inc. 


DIGITAL IMAGING 


99 Remember those classic 
wooden ABC blocks 
how easy it was to build anything our hearts 





growing up... 
desired! AccuSoft remembers and has updated its own building 
blocks. ImageGear 99 offers numerous technology choices on 

a simple plug-in basis, so your solutions can be developed as 
easily as your "younger" creations. 


ImageGear 99 provides many powerful imaging technologies 
while allowing you to still maintain low level control of your 
applications. These options will help you to increase the 
market potential for your existing products and make new 
application development a breeze. Our comprehensive line 
of imaging products include ActiveX, DLL, Java class libraries, 
Java Beans, and sophisticated Web server solutions. 


Let AccuSoft be your source and partner for imaging technology. 
Our strengths can be leveraged in many ways from toolkits to 
custom solutions. We want to show you how to improve your 
application development by building value one block at a time. 


Other AccuSoft imaging products: ImageGear Java - Pure Java imaging toolkit =» NetVue - The most powerful web imaging technology for OEMs, 
Integrators, VARs, and IT professionals. Winner of the “Best of AlIM’99” award in the “Web based document management’ category » DocVue - A document 
imaging component with many advanced features » Medical Imaging SDK - Advanced DICOM support » DICOM Communications SDK - Easy to use 
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ini connection technology is a Sun Microsystems invention de- 
signed to allow distributed systems of components to exist on 
many different platforms. Jini lets software and hardware com- 
ponents become seamlessly “federated” into a network through 
the use of Java technology. In this article, ll show how you can 
use Sun’s EmbeddedJava Application Environment tools to design 
and deploy a system that incorporates Jini technology into small 
memory footprint, network-enabled embedded devices. 

Jini connection technology lets anyone connect any device to 
any network in a simple manner. It provides mechanisms for 
software services or hardware devices to automatically join to- 
gether into a federation of Jini devices. The Jini services archi- 
tecture is built upon the Java distributed computing platform ar- 
chitecture. 

Devices in a Jini network are connected using Java Remote 
Method Invocation (RMI). This enables the Jini system to be 
secure and allows Java objects to move between Java Virtual 
Machines (VM) to implement the discovery protocol, join pro- 
tocol, and the lookup service. 

To form a Jini network of devices and services, a registration 
process occurs with a lookup service. When a device is con- 
nected to the network, it performs the discovery process and lo- 
cates the Jini lookup service where it uploads all of its interfaces 
for all its services and thereby joins the Jini network. The lookup 
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service also has the responsibility to behave as a control center 
to connect clients to a particular service. When that happens, the 
interface for the requested service is copied to the client. 

For its part, the EmbeddedJava Application Environment is de- 
signed for small memory footprint embedded devices, each one 
having a dedicated functionality. It consists of a set of tools that al- 
lows the configuration and compilation of an environment that con- 
tains only the necessary methods and fields for a specified appli- 
cation. There are tools in the EmbeddedJava Application Environment 
that generate an executable image. This executable has a complete 
environment that can be placed into the ROM of an embedded sys- 
tem. EmbeddedJava developers use the set of tools found in the 
EmbeddedJava Application Environment to build a wide assortment 
of products such as pagers, mobile phones, instrumentation, con- 
trollers, printers, peripherals, and networking equipment. 

The combination of the EmbeddedJava Application Environ- 
ment and Jini is a natural one. Jini connection technology pro- 
vides a way for small Java enabled devices to talk with each 
other, and the EmbeddedJava Application Environment enables 
you to build small devices that use the Java distributed com- 
puting platform. 


Hinkmond is an engineer in Sun’s Consumer and Embedded 
Division. He can be contacted at hinkmond@eng.sun.com. 
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Different Models for Using Jini Technology 

There are many ways to set up a Jini network. The different meth- 
ods are selected according to the requirements of the network. 
There are features in the current release of EmbeddedJava 1.0 
that can be used to integrate Jini devices. But since a Jini device 
depends on the Java 2 platform, there must be a proxy connect- 
ed to devices that use older Java platforms like EmbeddedJava 
1.0, which is based on JDK 1.1. 

For the easiest case to implement (that is, having a resident 
Java VM), the client needs to have a software proxy to a service 
that is located on a different machine running the Java 2 plat- 
form. This allows the service to take part in the lookup and dis- 
covery process of Jini connection technology (since it is built on 
the required Java 2 platform). The client must know beforehand 
how to contact the service and use its proxy software to make 
the necessary calls to the Jini service. 

There are drawbacks for the case of having a resident Java 
VM on the client. You need a high-performance CPU, enough 
memory, and a permanent storage device on the client system. 
This is not a good requirement for smaller consumer devices. 

Another possible design is to have a shared physical Java VM. 
This means that a higher performance system acts as a “bay” for 
Jini devices. This Jini bay should have a more powerful CPU, a 
good amount of memory, and a permanent storage device to han- 
dle the Java 2 platform. This enables the system to fully partici- 
pate in the Jini lookup and discovery process. This Jini bay has 
a Java VM that is shared among many clients directly connected 
to it. The Java VM becomes the only resource for the Jini clients 
by requiring the Jini clients to know how to communicate with 
the Java VM on the Jini bay via a customized protocol. 

The advantages of this model are that the Jini clients con- 
nected to the Jini bay don’t need a full Java 2 platform. This en- 
ables the devices to be smaller and use lower-cost CPUs. The 


disadvantage is that there needs to be some connection (most 
likely a serial connection) made from the client to the Jini bay, 
which will require some limited customized protocol. 

A third design is to have a Jini bay, existing somewhere on 
the network, that can talk directly over the Ethernet network to 
Jini devices. When a Jini client requests a special service, it com- 
municates over the network with that particular Jini bay. This 
relationship is known only between the Jini bay and its client 
devices. To the rest of the Jini network, this is transparent be- 
cause the Jini bay is acting as a proxy for its known devices to 
the rest of the federation. Here, I'll address this third design, 
with a Jini bay used as a proxy for an EmbeddedJava Applica- 
tion Environment client. This is the most likely case for using 
the Jini technology with EmbeddedJava 1.0. 


Developing a Jini Application 

To use the EmbeddedJava Application Environment to develop a 
Jini application, you need to proxy the Jini join-and- discovery pro- 
cess to the EmbeddedJava 1.0 client. This is done through a con- 
nection over the network (the third design model). 

To design an EmbeddedJava application using the Shared Net- 
work Java VM model, you first need an interface from the Em- 
beddedJava client to a Jini proxy, which, in turn, can connect 
to a Jini network. Because the Jini proxy requires the Java 2 
platform, all the Java 2 APIs are available for the Jini network 
join-and- discovery process. This gives flexibility for the proxy 
to handle the Jini environment while relaying pertinent infor- 
mation to and from the EmbeddedJava 1.0-based client to and 
from the Jini service. 

The exact design of the communication protocol between the 
Jini proxy and EmbeddedJava 1.0 client is dependent on the type 
of data that is needed between the client and service. The design 
of the protocol could be as simple as a Java Socket connection 
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(continued from page 22) 
over an Ethernet connection. I use a simple socket protocol in 
the example presented here. 

After designing the EmbeddedJava 1.0 client to the Jini proxy 
interface, the next step is to design the Jini proxy to the Jini ser- 
vice interface. Because the Jini proxy acts as a regular Jini client, 
this is a straightforward Jini client/service design. For this ex- 
ample, the Jini client is a printer client to the UNIX lp command 
acting as a service with a Jini wrapper. 

The steps to create the EmbeddedJava 1.0 Jini proxy client are: 


1. Write a Java program for the Jini proxy client. 

2. Use the JavaFilter tool to pare down a member list of de- 
pendencies to just the necessary methods and fields needed 
by the client. 

. Use the JavaCodeCompact tool to generate the Embedded- 
Java intermediate C file. 

. Compile and link the EmbeddedJava intermediate C file into 
an executable image meant for the target device. 


Pe Oe 


JavaFilter is an EmbeddedJava tool that produces a list of class 
members required by a specified Java program described by a 
set of Java compiled class files and a program specification. The 
member list is used by JavaCodeCompact in its -memberlist op- 
tion to generate an intermediate C file containing only the Java 
class members that are needed to run the Java program. 

The program specification is a list of command-line options 
that describe requirements for interfaces, entry points, class file 
location, and dependencies that are not automatically generat- 
ed by JavaFilter’s examination of class files (this happens in such 
cases as the names of classes referenced only by the method 
java.lang.Class forName( )). 
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You can then examine the member list generated by JavaFil- 
ter for repeated references to classes and any other anomalies 
before passing the list on to the JavaCodeCompact tool. 

JavaCodeCompact takes Java class files and combines them 
into a target-specific C file. This C file stores the given Java class- 
es in a preloaded internal format in its data structures. This C 
file is compiled and linked with the Java VM. 

The target-specific C file produced by JavaCodeCompact, along 
with a Java VM, is compiled and linked by a native C compiler 
and linker to produce an executable on the target system. This 
executable contains within it the Java VM and the specified Java 
classes that make up the embedded Java program. This is the fi- 
nal step of producing an EmbeddedJava application. 


Deploying Jini Applications 
To deploy Jini applications, you must execute a Jini client, Jini op- 
tional proxy, Jini service, and Jini lookup service. For example, the 
Jini client presented here is an EmbeddedJava program run on a 
small device target system, and the example proxy, service, and 
lookup service are run on a Java 2 VM on a larger system that can 
handle the high demands of the Jini services and proxy. 

To run the example, you need to complete these steps in order: 


1. Start the Jini lookup service: 
a. Start the Jini HTTP web server in Example 1(c). 
b. Start the RMI daemon in Example 1(b). 
c. Start the RMI registry in Example 1(c). 
d. Start the Jini lookup service in Example 1(a). 
2. Start the Jini service in Example 1(e). 


en 





Example 1: Starting the Jini lookup service. (a) Starting 
the Jini HTTP web server, (b) starting the RMI daemon; 
(c) starting the RMI registry; (d) starting the Jini lookup 
service; (e) starting the Jini service; (fP) starting the Jini 
proxy; (g@) starting the Jini client. 
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3. Start the Jini proxy in Example 1(f). 
4. Start the Jini client in Example 1(g). 


A Jini Application Example 

In the example I present here, the Jini service is a print service 
run on a UNIX system. The Jini service registers itself with a Jini 
lookup service. The print service allows a client to call through 
RMI to run UNIX shell commands to access the default UNIX 
printer connected to the network. The command can handle pa- 
rameters, such as the name of a file to print and the printer name. 
The files that implement this print service —PrintService java, 
PrintRemote.java, JiniPrintClient.java, and JiniPrintProxy.java— 
are available electronically; see “Resource Center,” page 5. 

The print service needs to have two parts. The first part is to 
use the Jini JoinManager() method to register itself with the Jini 
lookup service. This is done with a Jini method call, such as in 
Listing One. This allows the print service to find the instance of 
a Jini lookup service on the network. It attempts to join the 
lookup service and places its print service in the lookup registry 
according to the time set by the lease manager parameter ob- 
ject. The lease manager object prevents a service from becom- 
ing stale if it should die and not continue to renew its lease. 

The second part of the print service involves creating the inter- 
face to the printer UNIX shell commands. This is done by using 
a serialized object that will be marshaled to the Jini client through 
a socket. To create the print-service interface, follow these steps: 


1. Write a Java interface that extends Remote; see Example 2(a). 
2. Compile the class file with the javac compiler; see Example 2(b). 
3. Compile the class file with the RMI compiler; see Example 2(c). 


Two files will be generated: PrintRemote_Stub.class and Print- 
Remote_Skel.class. These two RMI files are used by the Jini net- 
work to move the PrintRemote object to the Jini client. In the 
example print service, the Java class extends PrintRemote and 
implements the calls for print() and checkQueue() to call the 
wrapper around the UNIX commands Ip and Ipq. In the Jini 
client, the PrintRemote object is transmitted by the proxy to the 
Jini client by using the writeObject() method on one end and 
readObject() method on the other over a socket connection. 
There is a cast made to the PrintRemote interface of the remote 
object coming from the proxy. The client can then call either 
the print) or checkQueue() methods at the print service. 

In the client, there are two steps that need to occur: 


1. Get the print service remote object from the proxy through 
a socket; see Listing Two. 

2. Call the print service method through the remote object in- 
terface; see Listing Three. 


(a) 
import java.rmi.RemoteException:; 
import java.rmi.Remote; 
public interface PrintRemote extends Remote [ 
String print(String printerName, String fileName) 
throws RemoteException:; 
String checkQueue(String printerName) 


throws RemoteException; 
j 


(b) 


javac PrintRemote. java 


(c) 


rmic PrintRemote 





Example 2: Creating a print-service interface. (a) writing 
a Java interface to extend Remote; (b) compiling the class 
file with the javac compiler; (c) compiling the class file with 
the RMI compiler. 
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This completes a Jini client to Jini service example using a proxy 








that marshals the remote object from a Jini-enabled Java 2 VM sys- References 

tem to a Jini-enabled EmbeddedJava 1.0 Application Environment 

client. By completing this connection, the final outcome is a Jini EmbeddedJava Overview | 

network utilizing the EmbeddedJava Application Environment to http://java.sun. com/proctucts/embeddedjava/overview. him! 

create a Jini Application built with EmbeddedJava 1.0 and Jini 1.0. Jini Information 
http://sun.com/jini/ 

Acknowledgment Jini Download 

I would like to thank Saeed Mokhtarani for help with the print http://developer.java.sun.com/developer/products/jini/ 

service example. Java 2 JDK 1.2) FCS Download 
http://java.sun.com:80/products/jdk/1.2/index. html 

DDJ 

Listing One service = (PrintRemote) objInStream.readObject(); 

; eae . // Close the socket 

import jini.net.JoinManager; socket.close(): 

// PrintService extends UnicastRemoteObject and implements } catch (Exception e) { 

// PrintRemote, Serializable e.printStackTrace(); 

PrintService service = new PrintService(); } 

ServiceInfo serviceInfo = new ServiceInfo(PRODUCT, MANUFACTURER, return(service) ; 


VENDOR, VERSION, "",""); } 
BasicServiceType basicServiceType = new BasicServiceType("PrintService") ; 
entry = new Entry[] {serviceInfo, basicServiceType}; 
try { e 4 
joinManager = new JoinManager(service, entry, new Listing Three 
ServiceIDHandler(), new LeaseRenewalManager()) ; 


} catch (java.io.I0Exception ioe) { } public String printToJiniService(String printerName, String fileName) { 


String retStr = null; 


if (service == null) { 


e e 
Listing Two // Get the PrintRemote object from the server 
; : ; ; service = getPrintService(); 
public PrintRemote getPrintService() { } 
Socket socket; try { 
InputStream inputStream; retStr = service.print(printerName, fileName) ; 
ObjectInputStream objInStream; } catch (Exception e) { 
try t e.printStackTrace(); 
// Open the socket for the ObjectInputStream } 
socket = new Socket ("<host>", PrintRemote.SOCKET) ; return(retStr) ; 
inputStream = socket.getInputStream() ; } 
objInStream = new ObjectInputStream(inputStream) ; 


// Read the PrintRemote object from the server DDJ 
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Internet Telephony 
Protocols 





H.323 versus SIP 





Linden deCarmo 


he H.323 protocol has so dominated 

Internet telephony that the two terms 

are considered synonymous. Despite 

H.323’s entrenchment, the creators of 
the Session Initiation Protocol (SIP) be- 
lieve they have a superior solution for con- 
trolling Internet phone calls. Are SIP’s ad- 
vantages enough to dethrone H.323? In 
this article, I'll discuss why this struggle is 
critical, examine the strengths and weak- 
nesses of the H.323 and SIP protocols, and 
provide insights about which technology 
will succeed. 

Before delving into the SIP versus H.323 
debate, I'll clarify some common miscon- 
ceptions about Internet telephony, or 
Voice over the Internet Protocol (VoIP). 
Most people assume that Internet tele- 
phony is limited to phone calls between 
two computers. In reality, VoIP refers to 
packetized audio streams transported over 
the Internet Protocol (IP) to endpoints 
where they are decoded. These endpoints 
can be computers, or even a normal ana- 
log phone (a gateway is required to con- 
vert the packetized audio to a format that 
your phone understands). 


Linden is a senior software engineer at 
NetSpeak and the author of The Core Java 
Media Framework (Prentice Hall, 1999). 
He can be contacted at lindend@ibm.net. 
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Another misperception about VoIP is 
that its primary benefit is free long-distance 
calls. While cheap long distance creates 
headlines, the reasons phone companies 
are attracted to Internet telephony are its 
ease of service creation and consolidation 
of networks. 


The primary advantage of VoIP over 
the Public Switch Telephone Network 
(PSTN) is the ease of adding new fea- 
tures and functions. For instance, you 
can create a video conference by defin- 
ing how the video stream is packetized 
and decoded. In contrast, retrofitting 
video conferencing support into the 
PSTN can be an arduous and expensive 
process. Similarly, since Internet Tele- 
phony is software centric, it is easier to 
add voice mail, call forwarding, and oth- 
er services to it. 






A second advantage for VoIP is the con- 
solidation of data networks. Currently, 
phone companies maintain duplicate net- 
works— one for voice, the other for pack- 
etized data. Because voice networks are 
approximately four to five times more ex- 
pensive than data networks, converting to 
VoIP eliminates the voice network, thus 
dramatically reducing costs. 

The final misconception about Inter- 
net telephony is poor transmission qual- 
ity. If the network is heavily loaded, there 
can be sizable transmission delays, which 
causes poor audio quality. However, if 
VoIP is rolled out on a dedicated private 
network with quality of service guaran- 
tees, audio quality rises to the level con- 
sumers expect. 


Signaling 101 

To complete a phone call, a signaling 
protocol is required to locate the party 
(or parties) you wish to call and alert 
the party with whom you desire to com- 
municate. Once you’ve located the 
callee, the protocol must reserve re- 
sources and prepare to stream the mul- 
timedia content. Furthermore, it must of- 
fer call-control features such as hold, 
forward, and transfer. 

As Figure 1 illustrates, most signaling pro- 
tocols focus on connection and call con- 
trol, and intentionally separate themselves 
from the actual transmission of multimedia 
content between endpoints. Consequently, 
the endpoints are able to stream multimedia 
content without the intervention of a third 
party. If the server transmitting the signal- 
ing protocol intervened in multimedia 
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(continued from page 30) 
transmissions, the extra processing could 
increase the likelihood of transmission 
delays; see Figure 2. 

Virtually all packet-based signaling pro- 
tocols use the Real-Time Protocol (RTP) 
to transmit audio-visual data between end- 
points using User Datagram Protocol 
(UDP). RTP is built on UDP because 
speed is paramount and lost packets can 
be compensated for in the audio or video 
Compressor/Decompressotr. 

Besides controlling Internet-friendly 
endpoints, signaling protocols must be 
able to interact and control PSTN end- 
points. This control is enabled by gate- 
ways (or bridges). A gateway is respon- 
sible for converting IP-based commands 
and packetized audio streams to tradi- 
tional protocols, such as Signaling System 
Seven (SS7) or ISDN, used by the current 
phone system. 

During the initial phases of Internet 
telephony, each vendor designed its own 
proprietary signaling protocol. Unfortu- 
nately, these phones and PSTN gateways 
could not interoperate and the Internet 
telephony market was in chaos. Fortu- 
nately, several standards bodies recog- 
nized the gravity of this problem and 
proposed open standards that theoreti- 
cally were to provide cross-vendor com- 
patibility. 
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Swiss Army Knife 

The first body to release a proposal was 
the International Telecommunication 
Union (ITU). The ITU’s Packet Based 
Multimedia Communication Systems 
(H.323) recommendation is an_all- 
encompassing definition of the protocols 
necessary to transmit multimedia streams. 
These protocols are described in the fol- 
lowing ITU recommendations: H.225 for 
connection, H.245 for control, H.332 for 
large conferences, H.235 for security, 
H.246 for interoperability with the PSTN 
world, and H.450.1, H.450.2, and H.450.3 
for supplemental services. All of these 
standards are part of the Series H rec- 
ommendations (hence the “H.” prefix) 
that cover audiovisual and multimedia 
systems. 

Because H.323 is composed of so many 
subrecommendations, you must wade 
through more than 700 pages of heavy 
technical reading before grasping its fea- 
tures. As you read these documents, you'll 








sources (such as routing and directory ser- 
vices) granted by a gatekeeper. Besides 
controlling local network resources, gate- 
keepers can interface with external gate- 
keepers to form Wide Area Networks; see 
Figure 3. 

H.225 applications typically send a Gate- 
keeper request (GRQ) to discover their 
gatekeeper, a Reservation request (RRQ) 
to request resources, and an Admission 
request (ARQ) to begin using the re- 
sources. When the call is complete, the 
application sends a Disengage request 
(DRQ) followed by an Unregister request 
(URQ) to deallocate resources. 

H.323 Version 1 (H323 V1.0) was 
plagued with poor performance and se- 
vere incompatibility problems between 
vendors. The first revision of a standard 
is often more concerned with architectural 
purity and functionality than performance, 
and H323 V1.0 typified this phenomena. 
For instance, to connect two parties, mul- 


tiple roundtrips between endpoints were 


be surprised to find out that, unlike most ‘necessary and this extended connection 


text-based Internet protocols, H.323 is a 
binary protocol based on Abstract Syntax 
Notation One (ASN.1) and the Packed En- 
coding Rules (PER). 

One of the most important H.323 pro- 
tocols is H.225, commonly referred to as 
RAS (Reservation, Admission, and Status), 
which lets a client application access re- 
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Figure 1: Separation of signaling from stream transition enables direct 
communication of mulimedia content between endpoints. 
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Figure 2: If the signaling protocol were involved in multimedia transmissions, 
overall throughput would be reduced because an extra party would have to 
process each buffer. 
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times from milliseconds to seconds (see 
Figure 4). 

In addition, because H.323 V1 was not 
feature rich, virtually every vendor added 
proprietary extensions to the protocol to 
maintain functional equivalence with their 
prior proprietary protocols. Unfortunate- 
ly, these proprietary extensions prevent- 
ed interoperation with other vendor’s 
H.323 products, thereby invalidating a ma- 
jor design goal of the standard. 

The ITU recognized these problems and 
addressed them in H.323 V2, which pro- 
vides the Fast Start feature that only re- 
quires one roundtrip to connect parties. 
Furthermore, features were added to the 
specification to reduce the necessity of 
adding proprietary extensions. 


A Different Philosophy 

The primary competitor of H.323 is SIP, 
which was conceived at Columbia Uni- 
versity and later submitted for considera- 
tion to the Internet Engineering Task Force 
CETF). Like other dominant Internet pro- 
tocols (such as HTTP for web browsing, 
and SMTP for mail services), SIP is text 
based. Unlike H.323, which has gone 
through two official revisions, SIP is an 
Internet draft (or work in progress) in the 
late stages of development. 

SIP focuses on signaling and does not 
try to define every aspect of multimedia 
communication, as H.323 does. Conse- 
quently, it can be documented in less than 
130 pages of relatively light reading. SIP 
achieves this feat by reusing other proto- 
col’s concepts and leveraging other pro- 
tocols for specific features. 

For example, SIP reuses the same head- 
ers, errors, and encoding rules as HTTP, 
so if you're familiar with HTTP syntax, 
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youll learn SIP syntax quickly. Similarly, 
SIP uses the IETF’s Session Description 
Protocol (SDP) to communicate attributes 








of the multimedia stream (CODECS used = munication, it must be combined with oth- 





Example 1: The Require informs the message recipient that it must be 
able to parse the com.reallyexpensive. billing header to complete the call. 


Example 2: How an unknown header should be rejected. Servers that can't 


to compress audio and video, data rate of 
the stream, and so on). 

Because SIP does not define every po- 
tential protocol used in multimedia com- 












process the header sent in Example 1 should reply with an error, and enumerate 
the incompatible header(s)— in this case, com.reallyexpensive. billing — under 
the unsupported reply header. 
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er IETF protocols to create a complete so- 

lution. For instance, you can use the play- 

back and recording features of the Real- 

Time Streaming Protocol (RTSP) to provide 

voicemail functionality with SIP. Since 

RTSP and SIP are text based and use SDP, 

the same SDP parser can be used for both 

protocols. 

Like HTTP, SIP is a client-server ar- 
chitecture. Clients invoke methods on 
servers, and servers respond with ac- 
knowledgments. There are three core 
methods in SIP: 

A 

e INVITE requests that a party join a con- 
ference (or call). 

e BYE terminates a connection between 
two users in a conference (hanging up 
the phone). 

e ACK acknowledges the reception of an 
INVITE request. 


Figure 5 illustrates the message flow be- 
tween an SIP server in proxy mode and 
a client machine. Each request or response 
is composed of headers (many of these 
headers are identical to their HTTP coun- 
terparts) and an optional message body. 
If an SIP parser encounters a header it 
doesn’t understand, it skips it and con- 
centrates on the headers it understands. 
The only exception to this rule is if the 
unknown header is listed in the Require 
header (see Examples 1 and 2). All head- 
ers specified by the REQUIRE header must 
be parsed or an error is returned to the 
sender. 

The Call-ID header is the most critical 
header and it can be found in virtually 
every request and response. It is a unique 
string that servers use to associate a mes- 
sage with the resources associated with 
a call. 

SIP commands are processed by three 
different types of servers: 


e Proxy servers receive SIP messages and 
forward the message for additional pro- 
cessing. 

e Redirect servers, by contrast, do not pro- 
cess messages, rather, they inform SIP 
clients of the address that will service 
their messages (this address can be a 
proxy, redirect and user-agent server). 
The client then uses the address pro- 
vided by the redirect server to connect 
the call. See Table 1 for additional com- 
parisons of SIP and H.323 message flow. 

e The final type of server is user agents, 
which are responsible for interfacing 
with end users and enable users to ac- 
cept, reject, and forward calls. 


Ready to Rumble 

Companies are divided into camps about 
which technology will succeed. SIP advo- 
cates point out that SIP has the advantages 
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over H.323 of simplicity, ability to grow, 
and scalability. The primary advantage of 
SIP over H.323 is its simplicity. Because it 
is a text-based protocol with only 37 head- 
ers to parse, you can have a fully func- 
tional SIP parser running very quickly. In 
fact, it is possible to write a useful SIP pars- 
er by implementing only three request 
types (INVITE, BYE, and ACK). Another 
significant advantage of SIP is that you can 
write a parser in quasi-interpreted lan- 
guages (such as Perl or Java) that excel in 
text manipulation because an SIP parser 
is lightweight. 

In contrast, H.323 requires you to parse 
hundreds of messages and complex data 
structures. Furthermore, because it is an 
intricate binary protocol, most vendors 
don’t write an ASN compiler or decom- 
pressor themselves. Rather, they purchase 
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the ASN compiler or decompressor from 
a third party and concentrate on process- 
ing and receiving messages. 

H.323’s complexity also complicates fire- 
walls. To process H.323 traffic, a firewall 
must understand the intricate web of 
H.323 protocols and associated state in- 
formation. An SIP firewall is marginally 
different from an HTTP firewall: The fire- 
wall need only process a single SIP mes- 
sage and need not maintain state infor- 
mation. 

H.323’s binary format has one signifi- 
cant advantage over a text-based proto- 
col— speed. It is quicker to identify and 
process a binary value than a textual 
string. Unfortunately, other than call set- 
up, speed isn’t critical for most signaling 
messages, thereby virtually negating this 
advantage. 
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Figure 4: Illustration of H.323 V1 performance woes. Several trips between 
endpoints are required to connect endpoints in H.323 V1. 


INVITE 


RTP Audio 








Figure 5: Message flow between an SIP server in proxy mode and client 


machine. 
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Because H.323 is a tangled web of in- 
terwoven protocols, it can be confusing 
to figure out the most efficient technique 
to accomplish a task. For instance, H.323 
provides three alternatives to control a call 
(the original multiround trip option, tun- 
neling the control protocol through the 
connection protocol, and the H.323 V2 
Fast Start option). Even more daunting is 
that H.323 V2 applications must support 
all three options to maintain backward 
compatibility with H323 V1. 

Another side effect of H.323’s numer- 
ous protocols is the duplication of func- 
tionality. For instance, both RTCP and 
H.245 provide similar stream feedback and 
conferencing controls. 


The Agony of 

Backward Compatibility 

The second advance of SIP over H.323 is 
its ability to adjust to new requirements. 
Internet telephony is transitioning from 
the trial stage to production use. Before 
it can replace the PSTN network, VoIP will 
have to increase reliability and quality, and 
dramatically increase the number of ser- 
vices. These changes require a signaling 
protocol that can easily incorporate new 
features. Simultaneously, as the changes 
are rolled out, backward compatibility 
must be maintained. 

Both SIP and H.323 can be extended, 
but they use different techniques to main- 
tain compatibility. SIP operates like HTTP 
and SMTP. If a parser encounters an un- 
known header, it skips over it. As a result, 
new features can be added to SIP with- 
out breaking older parsers. 

SIP errors also aid in extensibility. Like 
HTTP errors, SIP errors are grouped into 
six logical types (or classes) of errors, as 
shown in Table 2. Because the class of 
an error is detected by the first digit, old- 
er applications can analyze and under- 
stand new errors by examining that first 
digit. 

H.323 gives programmers access to 
the nonstandardParam field in ASN.1 
data structures to extend the protocol. 


H.323 Message SIP Message | 


@ 

Register | 
Admission | 
Call Setup 

Capabilities 
Fast Start 






REGISTER 
INVITE 







a2 





(b) 

Unregister 
Disengage 
Release Complete 





REGISTER 









Table 1: (a) Message flow comparison 
between SIP and H.323,; (b) call 
control method comparison. 
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Unfortunately, the nonstandardParam 
isn’t in every data structure, and there’s 
no way to determine what extensions a 
given implementation supports. Fur- 
thermore, because the protocol is bina- 
ry, it is impossible to determine the pur- 
pose of these extensions without talking 
with the person who created them. 


Thus, the difficulty of cleanly extending 
H.323 is the reason why interoperabili- 
ty has been so difficult to achieve. 
One unfair advantage SIP has over 
H.323 is it is still an evolving draft, while 
H.323 has endured two revisions and has 
considerable backward compatibility bag- 
gage to maintain. As a result, SIP design- 


: Informational 
: Success 

: Redirection 

- Client Error 

: Server Error 

: Global Failure 


Request received, continuing to process the request. 

Action was successfully received, understood, and accepted. 
Further action needs to be taken to complete the request. 
Request contains bad syntax or cannot be fulfilled at this server. 
Server failed to fulfill an apparently valid request. 

Request cannot be fulfilled at any server. 





Table 2: SIP errors are divided into six logical classes. Applications can 
determine the type of error by examining the first digit of the error. The 
remaining digits (xx) may be used for additional analysis. 


Protocol 


Functionality 


Multimedia streaming protocol. 

Playback and recording control over multimedia streams. 
Quality of Service Protocol. 

Real-Time Control Protocol for stream feedback and control. 
Session Announcement Protocol (conferencing). 


Table 3: SIP companion protocols. 
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Figure 6: SIP and H.323 interoperation. 
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Figure 7: H.323 zones permit H.523 to operate on large-scale networks. 
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ers are able to point out the deficiencies 
in H.323 while constantly refining their 
protocol to address weaknesses they un- 
cover. At some point, SIP will be official- 
ly released and the SIP designers will not 
be able to modify the specification as 
quickly. 


Modularity 

Is the Key to Growth 

The telephony industry is migrating away 
from proprietary protocols to open stan- 
dards. In addition, customers want solu- 
tions that interoperate with each other. 
For instance, a typical network may con- 
tain H.323 endpoints and SIP servers. 

The only way to ensure that a signal- 
ing protocol can interoperate with other 
signaling protocols is to create a platform 
that permits you to plug in new subfunc- 
tions (such as quality control, directory 
listings, content description, and confer- 
ence control). 

SIP’s architecture is like a set of Lego 
blocks. The core Lego block defines ba- 
sic call signaling, registration, and user 
location. SIP plugs in additional default 
protocols — or Lego blocks — to provide 
a richer set of subfunctions (see Table 
3). However, you can enhance SIP with 
additional protocols to enable cross sig- 
naling compatibility. For instance, you 
can plug in the H.245 capability exchange 
feature into SIP without affecting the core 
SIP protocol. 

Besides plugging in subprotocols (see 
Table 4), users can mix SIP and H.323 re- 
quests to get the best of both environ- 
ments; see Figure 6. For instance, you can 
use SIP’s superior directory features to find 
another user, and the SIP server can redi- 
rect you to an H.323 server to perform the 
actual call. 

Unlike SIP, H.323’s architecture is like 
a den of snakes. All the protocols are 
closely entwined and it’s dangerous, if not 
impossible, to try to separate them. 


Scaling Walls 

Scalability is the ability of a protocol to 
adjust to large networks and heavy load 
conditions. Protocols that were intended 
for a Local Area Network (LAN) usage 
have serious problems when they are 
placed on large networks. For instance, 
H.323 was originally designed for use on 
a LAN and it had poor directory capabil- 
ities and struggled with wide area ad- 
dressing. 

As Figure 7 shows, H.323 V2 attempts 
to address these limitations by defining 
“zones” (collections of gateways and end- 
points managed by a single gatekeeper). 
Although zones fix the issue of user di- 
rectories, they do not provide loop de- 
tection and prevention. SIP was designed 
to operate in Wide Area Networks and as 
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(continued from page 30) 
a result, provides loop detection algorithms 
to prevent infinite loop conditions. 
Another aspect of scalability is the 
number of calls that can be handled by 
a server. SIP permits servers to be state- 
less (that is, they do not have to main- 
tain call state throughout the life of the 
call). Therefore, they can process a re- 
quest, forward it to its destination, and 
move on to the next request. On the oth- 
er hand, H.323 requires gatekeepers to 
maintain state throughout the duration 
of a call. The lack of state and simpler 
protocol syntax means a server can pro- 
cess more SIP requests, and therefore 
potentially handle more calls than an 
equivalent H.323 server. 


Battle of the Compressors 
One of the vexing problems VoIP faces is 
voice quality. Although current audio Com- 
pressors/Decompressors (CODECs) are 
dramatically better than the initial algo- 
rithms, designers are constantly refining 
them to improve quality while simultane- 
ously reducing processing requirements. 
These rapid improvements mandate that 
the signaling protocol be able to pick the 
optimal CODEC supported by the end- 
points. 

SIP uses SDP to inform call parties of 
the CODEC that will be used during the 
conference. Because SDP describes 
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CODECs via descriptive strings, it can 
rapidly incorporate new CODECs. For 
example, if you created a CODEC called 
“KrystalClear,” you would register it with 
Internet Assigned Number Authority 
(IANA), pass KrystalClear in the SDP, and 
endpoints that supported this protocol 
could instantly begin using it. Because 
the IANA is the same organization that 
registers MIME types, this is a relatively 
painless process. 

In contrast, H.323 uses a big brother- 
like approach to control CODEC usage. 
H.323 only supports CODECs that have 
been approved and registered with a cen- 
tral authority. Once approved, CODECs 
are given a binary identifier (or code point) 
that is used by endpoints to describe 
CODECs. Although all popular CODECs 
are supported by H.323, this bottleneck 
could stifle the rapid adoption of new 
CODECS. 

Even though H.323 is not as flexible in 
accommodating new CODECs, it provides 
more robust capability exchanges between 


Ti able 4: Comparison of H. 323 subprotocols and approximate SIP equivalents. 


endpoints. For example, H.323 not only 





lets endpoints report the types of CODECs 
they support, but also numerous attributes 
that can be used by these CODECs. In 
contrast, SIP provides only rudimentary 
capability exchanges between endpoints. 


Services Are the Difference 

As mentioned earlier, the lure of easy 
service creation is what attracts compa- 
nies to VoIP. In the PSTN world, creat- 
ing a new service can cost millions of 
dollars and require years of development. 
An equivalent VoIP-based service can be 
developed and tested within days or 
weeks. Consequently, the VoIP signaling 
protocol that has the best service cre- 
ation environment will ultimately have 
the most applications and inevitably the 
most success. 

SIP was specifically designed for the 
smooth incorporation of new services. 
This is accomplished via service-specific 
request methods (such as INVITE, BYE, 
and OPTIONS) and headers. These meth- 
ods and headers enable an SIP server to 
create and destroy calls on external 
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servers. The external entities send status 
messages to the controlling SIP server on 
a periodic basis so that the originating 
SIP server can adjust in real time. Thus, 
your ability to add services to SIP is lim- 
ited only by your imagination. 

In contrast, the current revisions of 
H.323 permit you to write service exten- 
sions, but it is an arduous process. For ex- 
ample, the H.323 FACILITY command lets 
you transfer a call to a third party. How- 
ever, more exotic services, such as con- 
trolling a third-party call(s), require you 
to have intimate knowledge of the proto- 
col and willingness to spend vast quanti- 
ties of time figuring out how to properly 
implement them. 


Who Will Win? 

Although SIP and H.323 zealots believe 
their protocol will crush the competition, 
the VoIP signaling battle is not a zero 
sum game. Both H.323 and SIP will have 
their share of successes and each excels 
in different areas. SIP uses a decentral- 
ized approach that reuses principles pi- 
oneered by HTTP. Because of this open 
architecture, SIP will be able to adjust 
and grow as the VoIP market expands. 
H.323 is a well-defined centralized ar- 
chitecture that is expandable, but isn’t 
as extensible as SIP. 

In the near term, H.323 will dominate. 
Longer term, it is impossible to predict if 
H.323, SIP, or another protocol will ulti- 
mately replace PSTN. Only two things can 
be predicted with certainty— packet- 
based multimedia will eventually replace 
our phone networks and a variety of sig- 
naling protocols will have to interoper- 
ate in order to meet customer require- 
ments. 


For More Information 


Main SIP web site: 


http://www.cs.columbia.edu/ 
~hgs/sip/sip.html 


SIP FAQ: 
http://www.cs.columbia.edu/ 
~hgs/sip/faq. html 


SIP documents: 
http://www.cs.columbia.edu/ 

~hgs/sip/related.html 
SIP papers: 


http://www.cs.columbia.edu/ 
~hgs/sip/papers.html 


DDJ 
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UNIX makes 


Lifetime Support 


Free lifetime technical support 


Money-back Guarantee 
Get your money back for up to 60 days. 


UNIX Review Magazine Quote 
Editor Andrew Binstock said: “OpusMake 
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not using the make utilities bundled with 
today’s compilers.” 


"The complexity of today’s software development demands a make utility 
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things to think about. 


The premiere streaming video 
development toolkit is now 
available for creating the 
lowest bandwidth, highest 
quality streaming video 
around. Designed for C/C++ 
developers interested in 
moving video and game 
content to the web, 
Wavelet2000™ creates 
scalable, sharp VHS quality 
320 x 240 pixel video within 
baud rates as low as 28.8 
kbps! Wavelet2000™ is 
optimized for the Pentium Ill 
processor and useable as a 
Microsoft DirectShow filter or 
within the RealNetworks 
RealPlayer. Wavelet2000™ 
was created with Pegasus’ 
cutting-edge compression 
technology as a complement 
to our high-speed motion 
JPEG technology. Download 
Wavelet2000™ or its 
companion product, PiCVideo 
Wavelet CODEC, by visiting 
the Pegasus web site at 
www.jpg.com/wavelet2000. 
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X.509 Certificates 





Moving toward 
secure communication 





Pau! Tremblett 


igital certificates provide an impor- 
tant element of security— that of 
trust. One of the most popular stan- 
dards specifying the contents of a 
digital certificate is X.509, published by the 
International Telecommunications Union 
(ITU). In this article, I'll describe the ele- 
ments of an X.509 certificate, show how 
certificates are encoded, and present soft- 
ware you can use to decode and display 
them in a readable form. This software 
was originally developed using Squeak 
Smalltalk (which lends itself to rapid de- 
velopment), then converted to Java. 

A certificate is a document, issued by a 
trusted agent, stating that the public key 
of the person named in the document has 
a certain value. The concept of employ- 
ing the services of a trusted third party is 
not new— when you have a document no- 
tarized by a notary public, you do exact- 
ly that. The recipient of a notarized doc- 
ument trusts the stamp of the notary public 
and interprets its presence as proof that 
the person presenting the document signed 
it in the presence of the notary public. 

A digital certificate loosely parallels a 
notarized document. The role of the no- 
tary public is assumed by a Certificate Au- 
thority (CA) who employs a digital signa- 
ture rather than a stamp. The CA generates 
this signature by first computing a mes- 
sage digest of the certificate contents, then 
encrypting this message digest using the 
CA’s private key. The recipient of the cer- 
tificate decrypts the signature using the 
CA’s public key and the algorithm the CA 
used to perform the encryption, computes 
a message digest of the certificate contents 
using the same algorithm used by the CA, 
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and performs a comparison between the 
computed message digest and the one ac- 
companying the certificate. A match means 
that the contents of the certificate have 
not been tampered with, and that the cer- 
tificate was indeed signed by the CA. Also, 
based on the trust placed in the CA, the 
public key presented in the certificate re- 
ally belongs to the person named in the 
certificate. 

You are most likely to encounter cer- 
tificates when you use a web browser. Fig- 
ure 1 shows one of my digital certificates 
installed in Netscape Communicator. 


ASN.1 Definition of a Certificate 
The X.509 standard specifies a certificate 
using Abstract Syntax Notation (ASN.1), a 


| 1h os Faas ag 


language used to describe data types in 
such a manner as to eliminate ties to any 
particular platform. Here, I discuss only 
the subset of ASN.1 that is required to un- 
derstand a certificate. For more informa- 
tion on ASN.1, see the text box entitled 
“The Abstract Syntax Notation,” by Steve 
Witten, which accompanied the article 
“Packet Filtering in the SNMP Remote 
Monitor,” by William Stallings (DD/, 
November 1994). 

Figure 2 shows the ASN.1 representa- 
tion of a certificate as set forth in the In- 
ternet Draft entitled Internet X.509 Pub- 
lic Key Infrastructure — Certificate and 
CRL Profile produced by the PKIX work- 





ing group of the Internet Engineering Task 
Force (IETF). The latest version of this and 
several other useful documents related to 
certificates can be obtained by following 
the “Internet-Drafts” hypertext link on the 
IETF site at http://www. ietf.org/home.html. 

Take a look at the following ASN.1 state- 
ment found in Figure 2: 


CertificateSerialNumber ::= INTEGER. 


This defines the ASN.1 type CertificateSe- 
rialNumber as having the value INTEGER. 
CertificateSerialNumber is a simple type; 
it has no components. Figure 3 shows 
some simple types and their universal tag 
numbers. 

Now look at the ASN.1 statement: 


Certificate ::= SEQUENCE {| 
tbsCertificate TBSCertificate, 
signatureAlgorithm AlgorithmIdentifier, 
signatureValue BIT STRING} 


The ASN.1 type Certificate is a SEQUENCE 
of the components thsCertificate, signa- 
tureAlgorithm, and signatureValue; this 
ASN.1 type is called “structured.” Figure 
4 shows the four structured types defined 
by ASN.1, their universal tag numbers, and 
their meaning. Each of the components 
within a structured type appears as an 
identifier followed by its type. 


DER Encoding of a Certificate 
The definition of the certificate just pre- 
sented is abstract and only becomes use- 
ful when each of the ASN.1 values is con- 
verted to a series of Os and 1s and saved. 
The original rules for performing this op- 
eration were the Basic Encoding Rules 
(BER) as set forth in ITU-T Recommenda- 
tion X.209. I will not discuss BER; howev- 
er, if you study the recommendation, you 
will see that there is often more than one 
way to BER-encode an ASN.1 object. The 
X.509 specification eliminates possible am- 
biguity by using the Distinguished Encod- 
ing Rules (DER), a subset of BER that gives 
a unique encoding for any ASN.1 object. 
As with ASN.1, I will not discuss DER in 
its entirety, but just the amount required to 
understand how a certificate is encoded. 
DER is a tag/length/value encoding 
system in which each ASN.1 value is 
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Attracting and retaining customers requires applications 
that are not only entertaining and informative, but also 
easy to use. 





Jasmine's object technology is designed for building 
enticing systems that you get to market faster, develop 
more rapidly, and gain productivity through reuse and 
integration of code, data and applications. 


Just think how much more powerful your object tool 

would be with an object database like Jasmine™. ia 
With Jasmine’s pure, object-oriented architecture, 
objects defined in your application tool (C++, 
Java, and others) are the same as the objects 
managed by Jasmine. 

You can use native language bindings, rather than learning 
and coding new non-object-based data access protocols such as 
JDBC. And Jasmine supports large amounts of complex data so 
you can deliver true, next-generation applications. 

With Jasmine, objects never have to be converted to relational 
formats, so they run much faster. And there’s no need to choose 
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Jasmine Scene [Running] 








Today's business information is made up of not only text and 
numbers, but also images, motion, and sound. 


* Schedule - Jasmine Scene [Running] 


Only a pure object database like Jasmine inherently under- 
stands how to store and process complex data. Complex 
queries, such as fare comparisons for specific destinations 


and dates, are easily implemented with Jasmine. 
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between object models Jasmine supports 
both COM and Java. It even lets you use 
different tools at the same time. Jasmine’s 
object infrastructure also integrates 
external data and applications, making 
them accessible from any application 
development tool. 

That includes the object tool you're 
using right now. So call 1-888-7JASMINE or visit 
www.cai.com/ads/jasmine/dev for your FREE, full-function 
Jasmine Developer Edition CD. And turn your object tool into an 
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(continued from page 42) The bits are numbered, with bit 8 as the The first octet, called the “identifier 
represented as a series of octets, where most significant and bit 1 as the least octet,” is subdivided into three fields (see 


an octet is an 8-bit unsigned integer. 






This certificate incorporates the Ver1. 
Certification Practice Statement (CPS)> 
Use of this certificate is governed by . 


Figure 1: Digital certificate installed in Netscape Communicator. 


Certificate ::= SEQUENCE { 
tbsCertificate TBSCertificate, 
signatureAlgorithm AlgorithmIidentifier, 
signatureValue BIT STRING } 
TBSCertificate ::= SEQUENCE { 
version [@] EXPLICIT Version DEFAULT vl, 
serialNumber CertificateSerialNumber, 
signature AlgorithmIidentifier, 
issuer Name, 
validity Validity, 
subject Name, 
subjectPublicKeyInfo SubjectPublicKeyInfo, 


issuerUniqueID [1] IMPLICIT UniqueIdentifier OPTIONAL, 

-- If present, version shall be v2 or v3 
subjectUniqueID [2] IMPLICIT UniqueIdentifier OPTIONAL, 

-- If present, version shall be v2 or v3 


extensions [3] EXPLICIT Extensions OPTIONAL 

} 
Version ::= INIEGER (€ vi(@), v2{1), v3(2) } 
CertificateSerialNumber ::= INTEGER 


Algorithmidentifier ::= SEQUENCE { 
algorithm OBJECT IDENTIFIER, 


parameters ANY DEFINED BY algorithm OPTIONAL } 


Name ::= CHOICE { 
RDNSequence } 
RDNSequence ::= SEQUENCE OF RelativeDistinguishedName 
RelativeDistinguishedName ::= 
SET OF AttributeTypeAndValue 
AttributeTypeAndValue ::= SEQUENCE { 
type AttributeType, 
value AttributeValue } 
AttributeType ::= OBJECT IDENTIFIER 
AttributeValue ::= ANY DEFINED BY AttributeType 
Validity ::= SEQUENCE {( 
notBefore Time, 
notAfter Time } 
Time ::= CHOICE { 
utcTime UTCTime , 
generalTime GeneralizedTime } 
Uniqueldentifier ::= BIT STRING 
SubjectPublicKeyInfo ::= SEQUENCE { 
algorithm AlgorithmIdentifier, 
subjectPublicKey BIT STRING } 
Extensions ::= SEQUENCE SIZE (1..MAX) OF Extension 
Extension ::= SEQUENCE { 
extnID OBJECT IDENTIFIER, 
critical BOOLEAN DEFAULT FALSE, 
extnValue OCTET STRING } 





Figure 2: The ASN.1 definition of a certificate. 
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significant. 


-- If present, version shall be v3 


Figure 5). You use these fields to derive 
the tag mentioned earlier. Every ASN.1 val- 
ue has a tag that consists of a class and a 
nonnegative tag number. To overcome the 
limitation imposed by the fact that the 
largest number that can be represented us- 
ing 5 bits is 2-1 (31), two forms of tag 
are used. The first, or low-tag-number 
form, is for tag numbers between 0 and 
30. The second, or high-tag-number form, 
is for tag numbers greater than 30. In this 
form, bits 5 through 1 are all set to 1, in- 
dicating that the actual tag number is con- 
tained in one or more of the octets that 
follow. The tag number is represented as 
base 128, with bit 8 of each octet except 
the last set to 1. The order is from most 
significant to least significant. 

The identifier octet (or the last tag byte 
in the case of the high form of a tag) is 
followed by the length octet, which indi- 
cates how many of the following octets 
should be interpreted as contents octets. 
As is the case with tag, there are two forms 
of length. The short form consists of a sin- 
gle octet and is used when the length is 
between 0 and 127. The long form uses 
2 to 127 octets. For the short form, bit 8 
is 0 and the length is contained in bits 7 
through 1. For the long form, bit 8 of the 
first octet is 1 and bits 7 through 1 repre- 
sent the number of subsequent octets from 
which the length is to be derived: These 
octets represent the length base 256. The 
order is from most significant to least sig- 
nificant. 

The last length octet is followed by the 
number of contents octets indicated by 
the length octet; these represent the ac- 
tual value. Unlike the tag and length, 
which can be represented in two ways, 
the contents can be represented in sever- 
al ways. 


Decoding and Viewing Certificates 
Figure 6 shows the encoded portion of a 
sample certificate; it is one of many which 
you can find in Eric Young’s SSLeay pack- 
age (ftp://ftp.psy.uq.oz.au/pub/Crypto/SSL). 
In Figure 7 you can see that same certificate 
viewed using my Squeak Smalltalk X.509 
Certificate Browser. The code is available 
electronically as X509.st, which is suitab] 
for fileIn (make sure you are using Squeak 
2.3 or later). In the Squeak System Brows- 
er in Figure 8, the second column of the top 
pane shows all of the classes in the X509 
Category, which is highlighted in the first 
column. Notice how the class names corre- 
spond to the ASN.1 values in Figure 2. 
X509CertificateLister.java (Listing One) 
is a Java port of the Squeak Smalltalk cer- 
tificate viewer without the graphical in- 
terface. I'll use this code to discuss how 
you decode a certificate. Figure 9 shows 
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(continued from page 44) 

the output generated by X509Certifi- 
cateLister. You can see the content is iden- 
tical to that of Figure 7. 

X509CertificateLister creates an instance 
of X509Certificate and invokes the /for- 
mat() method on it. In X509Certificate. java 
(available electronically; see “Resource 
Center,” page 5), the constructor of class 
X509Certificate invokes the readCertifi- 
cate() method, which reads a file con- 
taining the certificate. The format of the 
file (Figure 6) is similar to that used by 
Privacy Enhanced Mail (PEM); the base 
64 encoded form of the certificate is sand- 
wiched between the delimiters “----BE- 
GIN CERTIFICATE ----” and “----END CER- 
TIFICATE.” The readCertificate() method 
discards everything before and after these 
delimiters and uses the class method de- 
code() of Base64 (available electronical- 
ly) to decode the contents into a byte ar- 
ray that is stored in the instance variable 
derCertificate. The parse() method de- 
composes derCertificate into ASN.1 val- 
ues. Those structured values are further 
decomposed. 

Before examining the parse() method, 
you should first examine ASN1Value.java 
(available electronically). The instance vari- 
ables class, tag, and length correspond to 
the components of an ASN.1 value I dis- 
cussed in DER encoding. The instance 
variable constructed is a Boolean that has 
a value of True if the ASN.1 value is a con- 
structed type and False if it is a primitive 





Figure 3: Some simple ASN.1 types 
and their universal tags. 


type. The instance-variable data holds the 
contents octets that, as you will see, can 
be retrieved in a variety of ways or parsed 
into further ASN1Value objects. The re- 
maining instance variable, totalLength, is 
a helper that represents the total number 
of bytes consumed from derCertificate to 
create this ASN1 Value. 

If you look at the parse() method of 
X509Certificate, you can see that the first 
code it executes is: 


certificateSequence = new 
ASN1Value(derCertificate, 0); 


To see how this instance of ASN1 Value is 
created, look at the constructor for 
ASN1 Value. It receives two arguments; the 
first is a byte array from which it is to ex- 
tract and decode the data comprising the 
ASN.1 value; the second is the position in 
the array at which it is to begin. It starts 
by setting the variable b to the value of 
that byte of the array specified in the sec- 
ond argument. You can see from Figure 
10 that b now has a value of 0x30 (I’m us- 
ing byte and octet interchangeably). It then 
performs a logical AND of b and ASN1- 
Constants. MASK_CLASS, which has a val- 
ue of 0xCO; this extracts bits 8 and 7 
which, as you can see from Figure 5, rep- 
resents the class. In the present case, the 
class is universal. It next performs a log- 
ical AND of 6 and ASN1Constants.MASK_ 
BITO and, if the result is not zero, sets the 
instance variable constructed to True; oth- 
erwise, constructed retains its initial val- 
ue of False. Again, referring to Figure 5, 
you can see that bit 6 is the bit used to 
indicate whether the ASN.1 value is con- 
structed. Bit 6 in the present case has a 
value of 1, so the instance variable con- 
structed is True. The constructor code now 
performs a logical AND of b and ASN1- 
Constants.BITS_5_1 to isolate what Fig- 
ure 5 shows as being the tag. If the result 
is equal to ASN1Constants.BITS_5_1 (that 
is, all bits are 1), method decodeHighTag() 





Figure 4. The structured ASN.1 types and their universal tags. 





Figure 5: Breakdown of the identifier octet. 
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is invoked to extract the tag using addi- 
tional octets. In the present case, the tag 
is in low-tag-number form and has a val- 
ue of 0x10, which Figure 4 shows is the 
universal tag for SEQUENCE. The code 
next sets p to the start position it received 
in argument two plus the number of bytes 
that make up the tag (in this case, 1; in 
the case of a high-tag-number form of the 
tag, the value returned by decodeHigh- 
Tag()). From Figure 10, you can see that 
D is now pointing to position 1 in derCer- 
tificate, this is the length octet, which has 
a value of 0x82. Remember that there are 
two ways of encoding length as indicat- 
ed by bit 8. In the present case, bit 8 has 
a value of 1, indicating that this is the long 
form; bits 7 through 1 have a value of 2, 
indicating that the length is contained in 
the two octets that follow. This code de- 
codes the length: 
length = 0; 
for Gint j = 0; j < (Gnbdb) & 
ASN1Constants.BITS_7_1); ++j) { 
ED; 
length = (length << 8) | (arraylp] & 
ASN1Constants.BITS_8_1)); 


The logical AND with ASN1 Constants 
.BITS_8_1 is performed because Java 
propagates the high-order bit of a byte 
to the left. 

You can see that length is tested for 
a value of 0; this is a special case that 
indicates a form of encoding, known as 
“indefinite-length encoding,” is being used, 
in which case the end of this ASN.1 val- 
ue’s data is marked by two consecutive 
zero-value octets. There has been much 
debate as to whether indefinite-length en- 
coding belongs in certificates and such dis- 
cussion is beyond the scope of this article. 

After the length has been computed, p 
is incremented to point to the contents 
octets that are extracted and stored in the 
instance-variable data. 

Now that you have seen how an instance 
of ASN1 Value is created, the remainder of 
the certificate decoding is easy. The parse() 
method of X509Certificate creates three in- 
stances of ASN1 Value. The first two are 
passed to the constructors of X5O9TBSCer- 
tificate and X509AlgorithmIdentifier. The 
third is saved in the instance variable sig- 
nature. The constructors of XSOOTBSCer- 
tificate and X509Algorithmldentifier parse 
the ASN1Value objects they receive as ar- 
guments into other ASN1 Value objects that 
are either saved in instance variables or 
passed as arguments to the constructors of 
other classes. This process continues to the 
level of nesting of structured ASN.1 values 
in the certificate. 

The first ASN.1 value extracted by the 
parse() method is an instance of X509TBS- 
Certificate (available electronically). This 
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(continued from page 40) 

ASN.1 value is a SEQUENCE of ASN.1 
types representing those items “to be 
signed” by the CA; hence “TBS.” Since 
you have now seen the parsing mecha- 
nism, I will just point out some of the 
TBS elements. 

I will start with SerialNumber because, 
as you will see, Version is a slightly un- 
usual case. SerialNumber (at Ox000D) is 
an INTEGER. An ASN.1 INTEGER can be 
positive, negative, or zero and can have 
any magnitude. The contents octets give 
the value, base 256, in two’s complement 
form from most significant to least signif- 
icant. The minimum number of octets is 
used, so you will find no leading zeros. 
The value 0 is encoded as a single octet 
having a value of 0. If you examine the 
getInteger() method of ASN1 Value (avail- 
able electronically), you can see how Se- 
rialNumber is decoded. For this certificate, 
the serial number is 1. Each certificate is- 
sued by a CA must have a unique serial 
number. 

Version may or may not be present in 
a certificate. If the version is absent, the 
certificate is assumed to be Version 1. To 
present, there are three possible versions 
of X.509 certificates. The presence of Ver- 
sion is indicated by an identifier octet with 
a value of OxAO, which decodes as a class 
of context specific, a type of constructed 
and a tag of 0. At 0x0008, you can see just 
such an identifier octet. The definition of 
Version in Figure 2 reads: 


version [0] EXPLICIT Version DEFAULT v1 


where Version is defined as: 
= INTEGER { v1(0), v2(1), v3(2) } 


The word EXPLICIT refers to a type of 
tagging called “explicit tagging.” Tagging 
provides a way to differentiate between 
different context-specific types. An ex- 
plicitly tagged type is a type derived from 
another type by adding an outer tag to 
the underlying type. In this case, the un- 
derlying type is the INTEGER found at 
OxO00A. When present, the value of the 
INTEGER is always one less than the ac- 
tual version number. As you can see from 
the single content octet at Ox000C, this is 
a Version 3 certificate. 

Signature (at 0x0010) is an Algorithm- 
Identifier type. From the ASN.1 defini- 
tion in Figure 2, you can see that 
Algorithmldentifier (available electroni- 
cally; see X509Al gorithmIdentifier.java) is 
a SEQUENCE in which the first field (at 
0x0012) is an OBJECT IDENTIFIER whose 
universal tag is 6. An OBJECT IDENTI- 
FIER (OID) is a series of integers that 
identifies some kind of resource. Exam- 
ples of resources that can be represent- 
ed by an OID include a registration au- 
thority that itself assigns OIDs, a 


Version 
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cryptographic algorithm, or a directory 
name. The HashtableoidMap in ASN1- 
Constants.java (available electronically) 
shows a number of OIDs and their trans- 
lations. The integer components of an 
OID are separated by a “.” and are or- 
ganized hierarchically in much the same 
manner as Internet domain names (for 
instance, all 1.n identifiers are controlled 
by 1 and all 1.2.n identifiers are con- 
trolled by 1.2, and so on). You can see 
how an OID is decoded if you look at 
method getO/D() in ASN1Value .java 
(available electronically). The first num- 
ber of an OID always has a value of 0, 
1, or 2. If it is O or 1, the second num- 
ber is limited to a range of 0 through 39. 
These limitations allow the first two num- 
bers to be encoded in the first contents 
octet as (val1x40)+val2. All OIDs must 
consist of at least two numbers. The re- 
maining numbers of the OID are en- 
coded base 128 using the least possible 
number of digits. For each series of 
octets used to represent a number with- 
in the OID, all but the last have the most 
significant bit set to 1. 

You would decode the signature (at 
0x0010) as follows: The first two bytes 
identify the ASN.1 value as having a class 
of universal, a type of constructed, a tag 
of 0x10 (SEQUENCE), and a length of 13. 
The first ASN.1 value in the SEQUENCE 
starts at Ox0012 and is, as you can see 





from the first two bytes, an OID with a 
length of 9 octets. The first octet repre- 
sents the first two numbers 1.2 (1x40+2). 
The next number in the OID is encoded 
in the bytes located at 0x0014 and 0x0015 
(the byte at 0x0015 terminates the se- 
quence because its most significant bit is 
0). These two bytes represent the deci- 
mal number 840, represented in base 128. 
The bytes at 0x0016 through 0x0018 sim- 
ilarly represent the decimal number 
113549. Continuing until all nine bytes of 
the OID have been decoded, you finish 
with 1.2.840.113549 .1.1.4 which, if you 
check oidMap, represents md5WithRSA- 
Encryption. 

If you wish to fully explore the hierar- 
chy of OIDs, see http://www.alvestrand 
no/~hta/objectid/, which contains a link 
that lets you “walk” the entire OID tree. 
If you do, you would see that the com- 
plete translation of the OID you decoded 
above is: 


1 - ISO assigned 

2 - ISO member body 

840 - US 

113549 - RSADSI 

1 - PKCS 

1 - PKCS-1 

4 - MD5 with RSA encryption 


The second ASN.1 value in the SE- 
QUENCE is the universal type NULL en- 


: (seize W:z800 LEM ycacert.pem | 


f.pe 


128: Were 
{1998.12.16 10:28:40 2,945) ICE-CA. pem 


509 Certificate Version: 3 Serial Number: 1 _ 


Issuer: O-European ICE-TEL project, OU=V¥3-Certification Authority, L=Darmstadt 


| Not valid before; 2 April 1997 5:35:59 pm 
| Not valid efter: 2 April 1998 5:35:59 pm 


| || | Subject: O-European ICE-TEL project, OU=V3-Certification Authority, L-Darmstadt, CN-USER 


| Subject Public Key Algorithm: 2.5.8.1.1 (rea) 


| Public Key: 





coded in the two bytes at 0x001D and 
OxO01E. This ASN.1 value represents the 
algorithm parameters— in this case, 
none. 

Issuer (at OxOO1F) and subject (at 
Ox009D) identify the party who signed 
and issued the certificate and the party 
to whom the certificate was issued, re- 
spectively. Both fields are the ASN.1 rep- 
resentations of an X.501 name. Referring 
to Figure 1, you can see that if you fol- 
low the definition of Name down through 
the levels of nesting, it ultimately con- 
sists of a RelativeDistinguishedName. If 
you have used or encountered X.500, you 
will recognize the term “relative distin- 
guished name.” Figure 2 defines Rela- 
tiveDistinguishedName as a SET of Af- 
tributeTypeAndValues where’ each 
AttributeTypeAndValue is a SEQUENCE 
of an OID followed by a string. If you 
decode these OIDs using the technique 
I explained earlier, you will notice they 
are all of the form 2.5.4.n. Walking the 
OID tree gives: 


2 - Joint ISO/ITU-T assignment 
5 - Directory (X.500) 
4 - Attributes 


The fourth number in the OID is one of 
the following (and this is only a partial set): 


3 - Common Name (CN) 

6 - Country Name (C) 

7 - Locality Name (L) 

8 - State/Province Name (S) 
10 - Organization (O) 

11 - Organizational Unit (OU) 


The identifiers in parentheses are the ones 
you have more likely seen in distinguished 
names. X509Name.java is available elec- 
tronically. 

validity (at 0x007D) is a SEQUENCE of 
two dates. The first (at 0x0080) is the date 
before which the CA will not vouch for 
the validity of certificate; the second (at 
OxOO8F) is the date after which the cer- 
tificate is to be considered invalid. The 
contents octets of each date contain the 


date in the form YYMMDDHHMMSSZ. If 
the two-digit-year field is greater than 50, 


———--30:48:02:41:00:48:48:53:63:49:1B:93:C3:C3:0B:6C: 
ts 68: 1:55:DE:7E:6A:E2:F9:52:A0:DC:69:25:C4:C8:BE: 
— SS:E1:31:A8)CE:E4:49:29:85;99:8.4:15:9A DE: F6:2E: 
oS ee ee 


2 5 29. DD Seer 
2.5.29.14 (subjectKeyldentifier) 
2,5.29.15 (keyUsage) CRITICAL 
2.5.29.32 (certificatePolicies) CRITICAL 
2.5.29.17 (subjectaAlternativeName) 
25.29.18 CissuerAlternativeName) 
2.5.29.19 (basicConstraints) CRITICAL 
2,5.29.31 (cRLDistributionPoints) 


| Signature Algorithm: 1.2.840.113549.1.1.4 (md5WithRSAEncryption ) 





n | Signature: 
69:00: EL:B?7: A7:F2:D8:FB:E6:69;C0:13:CD:37:AD:21: 
06:22:4D;E6;C6:DB:F1,04:0B:57:E0:53;D6;0C:81:03: 


Figure 8: The second column of the 
top pane shows all of the classes in the 
X509 Category, which is highlighted 
in the first column. 





Figure 7: Certificate viewed using Squeak Smalltalk X.509 Certificate Browser. 
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you interpret it as 19YY; otherwise, you 
X509 Certificate Version: 3 Serial Number: i interpret it as 20YY. Dates later than 2050 
Issuer: O=European ICE-TEL project, OU=V3-Certification Authority, must use the ASN.1 value Generalized- 


L=Darmstadt ; ; ‘ 
) represents th 
Not valid before @2 Apr 1997 17:35:59 Time, which epresents {he date as 


Not valid after 02 Apr 1998 17:35:59 YYYYMMDDHHMMSS. In X509Validity 


Subject: O=European ICE-TEL project, OU=V3-Certification Authority, java (available electronically), the date- 
L=Darmstadt, CN=USER Fr Stri o() thod uses th CO) 
Subject Public Key Algorithm: 2.5.8.1.1 (rsa) rPOMOIVING( ie od uses the parse 
Public Key: method of the SimpleDateFormat class to 
30:48:02:41;:00:a8:a8:53:63:49:1b:93:c3:c3:Ob: 6c: ‘* 
88:11:55:de:/7e:6a;e2:£9:52:a8:de:69:25:c4:c8:ibt: extract d UTC Time. 
55:e1:31:a8:ce:e4:a9:29:85:99:8a:15:9a:de:f6:2f: subjectPublicKeyInfo (at 0x010A) con- 
e1:b4:50:5f:56:04:75:a6:£4:76:de:3c:@e:39:de:3a: tains an algorithm (at 0x010C) and a key 
be:3e:a4:61:8b:02:03:01:00:01 . : 
Extensions: to be used with the algorithm (at 


2029. — 0x0118). The algorithm is encoded as an 
pee sup jectKe entitier 
Ce a -cetticales OID that you have already seen, and the 


(certificatePolicies) **CRITICAL** key is encoded as a BIT STRING; see 
ee ee X509SubjectPublicKeyInfo, available 


(issuerAlternativeName) ; 
5. (basicConstraints) **CRITICAL** electronically. 

2.5.29, (eRLDistributionPoints) ; ; i] n exist on 
Signature algorithm: 1.2.8409.113549.1.1.4 (md5WithRSAEncryption) : Extensions (at Ox0 65) ee . aaa ly for 
Signature: Version 3 certificates. Extensions provide 

41:00:69:0c:e1:b/:a/:£2:d8?fb:68:69:cO:13:cd:37: 4a mechanism for associating additional at- 

ad:21:06:22:4d:e8:c6:db:£1:04:0b:b/:e0:b3:d6:9c: 15 th ; Lie i Th 
81:93:ce:c3:6a:3e:c/:e/:24:24:a4:92:64:¢2:83:83: trl utes with users Or PUDHC Keys. € 
06:42:53:0e:6£:09:16:84:9a:f7:6F:63:9b:94:99:83: identifier octet at 0x0165 decodes as a class 

7 of context specific, a type of constructed, 


and a tag of 3. As you saw with Version, 








Figure 9: Certificate formatted by X509CertificateLister.java. Extensions is an explicitly tagged type. The 
underlying type is the SEQUENCE at 

—FDULUmUrUrrC—~—msS—SSC oe 0x0169. The length of this SEQUENCE is 
2000 , , : the long form of /ength since bit 8 of the 
ae soe ee eee octet at Ox016A is 1. The length, as derived 
aan: from the two bytes that follow, is 404. Each 
0004 element of the SEQUENCE consists of an 
oo) OID and an associated ASN.1 structure. I 
2070 only report the OIDs; see X509Extension, 
aeca available electronically. 
QOA9 21 30 1F © : “AE The second ASN.1 value extracted by 
sae the parse() method of X509Certificate is 
gone : the signature algorithm (at 0x0301). This 
00E0 identifies the cryptographic algorithm the 
ee | oa ee CA used to sign the certificate. The algo- 
0110 55 88 01 61 O2 02 02 OG 03 4B 00 30 48 2 41 00 rithm is represented as an OID. 
We ae The third ASN.1 value extracted by 
0140 BA AS 29 85 9: ‘9A DE FO 2F Ei B4 50 5F 5E parse() is the digital signature (at 0x0310), 
ae 2 . Se oe which you can see has a class of univer- 
o170 se sal and a type of BIT STRING. 
@18O © 
pe Conclusion 
0130 Now that you have examined software 
oe that decodes an X.509 certificate, you can 
1E0 see that working with one is not terribly 
see difficult. I should point out, however, that 
aoe you will encounter certificates the soft- 
es ware cannot decode. This unfortunate sit- 
0240 uation results from the fact that software 
9250 used to encode certificates takes its rules 
oo from a profile rather than from the spec- 
0280 ification. A specification leaves room for 
Lge interpretation, and this interpretation is 
giao done by a profile. A profile is a specifi- 
Jae cation with an attitude. You can get an 
one 3 idea of the variety of profiles in use and 
02F0 the quirks of each from the document 
ee! X.509 Style Guide by Peter Gutmann at 
2320 http://www.cs.auckland.ac.nz/~pgut001/ 
oe pubs/x509guide. txt. 
0350 

Figure 10: Contents of the byte array derCerttificate. | DDJ 
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Listing One 


import com.beechwood.certificates.*; 
import java.io.*; 
public class X509CertificateLister { 
public X509CertificateLister (String fileName) { 
try { 
format (new X509Certificate (fileName) ) ; 
J 
catch (X509CertificateException e) { 
System.out.println(e.getMessage()); 
System.exit (Q) ; 
} 
} 
private void format (X509Certificate cert) 
throws X509CertificateException { 
X5O09TBSCertificate tbsCertificate = cert. getTBSCertificate(); 


System.out.print("X509 Certificate Version: " + 
tbsCertificate.version()); 
System.out.println(" Serial Number: " + tbsCertificate.serialNumber()); 


System.out.println(); 

System.out.print("Issuer: "); 

System.out.println(tbsCertificate.issuer().getRDN()); 

System.out.printin(); 

System.out.print("Not valid before "); 

System.out.println(tbsCertificate.validity() .notBeforeDateString()); 

System.out.print("Not valid after "); 

System.out.println(tbsCertificate.validity() .notAfterDateString()); 

System.out.println(); 

System.out.print("Subject: "); 

System.out.printin(tbsCertificate.subject().getRDN()); 

System.out.println(); 

System.out.print ("Subject Public Key Algorithm: "); 

X509AlgorithmIdentifier algorithm = 
tbsCertificate.subjectPublicKeyInfo().algorithm() ; 

System.out.print (algorithm. getOID()); 

System.out.println(" (" +algorithm.getOIDDescription() + ")"); 

System.out.println() ; 

System.out.println("Public Key:"); 

String subjectPublicKey = tbsCertificate.subjectPublicKey() ; 

int ix = Q; 

while ((ix + 48) < subjectPublicKey.length()) { 


System.out.println(" " + subjectPublicKey.substring(ix, ix + 48)); 
ix t= 48; 

} 

if (ix < subjectPublicKey.length()) 
System.out.println(" " + subjectPublicKey.substring(ix)); 


System.out.println(); 
X5@9Extension[] extensions = tbsCertificate.getExtensions() ; 
if (extensions.length > @) { 
System.out.println("Extensions:") ; 
for (int i = @; i < extensions.length; ++i) { 
System.out.print(" " + extensions[i].id()); 








System.out.print( " (" + extensions[i].idDescription() + ")"); 
if (extensions[i] .isCritical()) 
System.out.print(" **CRITICAL**") ; 
System.out.println() ; 
} 
} 
System.out.print1n(); 
System.out.print("Signature algorithm: "); 
System.out.print(cert.getSignatureAlgorithm().getOID()); 
System.out.println(" (" + cert. getSignatureAlgorithm(). 
getOIDDescription() + ")"); 
System.out.println(); 
System.out.println("Signature:") ; 
String signature = cert.getSignature(); 


ix = @; 
while ((ix + 48) < signature.length()) { 
System.out.println(" " + signature.substring(ix, ix + 48)); 
ix += 48; 
} 
if (ix < signature.length()) 
System.out.println(" " + signature.substring(ix)); 
System.out.println() ; 


} 
public static void main(String[] args) { 
if (args.length != 1) { 
System.out.println("Usage: X509CertificateLister certFile") ; 
System.exit(Q) ; 
} 
X509CertificateLister lister = new X509CertificateLister(args[@]); 
System.exit (@) ; 
} 
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The HTTPsyne 
Incremental Update 





Saving time 


and bandwidth 





Forrest J. Cavalier II 


oftware developers with collections 
of files to share and distribute often 
use a compressed archive format such 
as ZIP or tar.gz for transfer. But com- 
pressed archives are inconvenient to 
browse, and they waste bandwidth when 
only updates are needed. Even in a rapid- 
ly evolving open-source software project, 
active development usually affects a very 
small subset of files. When an update is 
needed, therefore, it is unlikely that com- 
pression will make up for the unneces- 
sary transfer of a large number of un- 
changed files also in the archive. Storing 
a collection as individual files makes them 
much easier to browse and maintain. Only 
files that change need to be updated. 
HTTPsync, the utility I present here, is 
client-side-only software that performs 
fast and efficient incremental updates to 
synchronize collections of files. Only the 
standard features of HTTP are used. No 
special protocols, server software, or dae- 


Forrest provides consulting services and soft- 


ware development through Mib Software. He 
can be contacted at forrest@mibsofiware.com. 
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tility 


mons are needed. HTTPsync, available 
electronically from DDJ/ (see “Resource 
Center,” page 5) and from http://www 
.mibsoftware.com/, is implemented as a 
C source file that compiles for Windows 
and UNIX-like SS 
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Using HTTP for File Distribution 

Hypertext Transfer Protocol (HTTP) is a 
good base protocol for file distribution. A 
single stream socket connection is used 
to make a request and return the data. 
This simplifies the implementation of 
clients and servers. In comparison, FTP 
requires a control connection and a sep- 
arately arranged data connection. CVSup 
also uses a two-connection approach, with 
a special protocol. Special protocols and 
ports are often blocked by firewalls that 











are configured to pass only HTTP requests 
and data. 

HTTP servers are ubiquitous and avail- 
able for just about every operating plat- 
form. Nearly every software developer can 
publish web pages at little or no extra cost. 
The general-purpose nature and simple 
protocol allows the design of HTTP servers 
for efficient handling of large numbers of 
requests, as well as caching intermediaries 
and proxies. HTTP/1.1 supports multiple 
requests and data returns over a single 
connection, which avoids connection set- 
up and tear-down overhead when a large 
number of files must be transferred. 

In contrast, many popular file distribu- 
tion systems, including CVSup, Sup, track, 
rdist, cvs, and rsync, require privileged- 
port server-side daemons, which are not 
easily available for all platforms. CVSup 
is implemented in Modula-3, for example. 
A survey of other systems and compari- 
son to HTTPsync is available at http:// 
www.mibsoftware.com/httpsync/. 

HTTP does lack methods that some spe- 
cially designed protocols and software use 
to implement efficient incremental updates. 
There is no method to determine which 
files are part of a collection or which have 
changed. The “If-Modified-Since” request 
header allowing conditional transfer is ig- 
nored by some servers (the protocol al- 
lows this if the data is always sent). Even 
if all servers supported this header, mak- 
ing a separate request for each file would 
be an inefficient way to find 10 changed 
files in a collection of 500. The “Last-Mod- 
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(continued from page 52) 

ified” response header, which provides 
time stamp information, is not always pro- 
vided reliably. Read/write/execute per- 
missions are not handled within the pro- 
tocol at all. HTTPsync shows a way to 
overcome these limitations with client-side- 
only software. No modifications to the 
protocol or the server are required. 


A Client-Side-Only Solution 

To distribute a collection of files using 
HTTPsync, you store on the server a 
packing list that describes the collection. 
For all the files in the collection, the 
packing list includes path names relative 
to the current directory, sizes, time 
stamps, and read/write/execute permis- 
sions. HTTPsync first obtains the pack- 
ing list specified at run time by a URL, 
then compares it to the local status of 
files to determine which are needed for 
incremental update. HTTP GET requests 
are made, and the files are stored with 
the time stamp and status bits provided 
by the packing list. The ownership of the 
files is naturally whatever user is run- 
ning HTTPsync. 

HTTP/1.1 persistent connections are 
used when possible, but a fallback to 
HTTP/1.0 happens after a small number 
of attempts. (Poorly implemented caches 
and proxies can cause this, even if the 
source server supports HTTP/1.1.) 

From this design, the implementation is 
straightforward and the software is writ- 
ten for use on UNIX-like and Windows 
systems. As a simple client, there are no 
advanced features found in other incre- 
mental file distribution protocols. If you’re 
used to working with CVSup, it is impor- 
tant to note that HTTPsync does not merge 
local changes — rather, it synchronizes the 
local copy to the remote copy exactly. Lo- 
cal changes will be overwritten regardless 
of source and destination time stamp or- 
dering. Merges with local changes can be 
accomplished with CVS, patch, or other 
software external to HTTPsync. 


Common Code 

For WinSock and BSD Sockets 

With a few conditional defines and code 
blocks, HTTPsyne compiles cleanly on 








es Eamets 


Example 1: Use HTTPsync 


oe 


54 


—m to generate packing lists. 


One. The most important difference be- 
tween the systems is that WinSock sock- 
ets are not file descriptors. HTTPsync is 
written using macros readsocket, write- 
socket, and closesocket, which are defined 
conditionally to be recv, send, and close- 
socket for WinSock, and read, write, and 
close for BSD sockets. The WIN32 pre- 
processor definition controls which head- 
er files are included and the WSAStartup 


HTTP is a good 


base protocol for 
file distribution 





and WSACleanup calls needed under 
WinSock. This organization allows the 
sockets code to be platform independent. 

There are some other differences in file 
handling controlled by WIN32 as well. Un- 
der the MS-DOS FAT file systems, time 
stamps have a two-second resolution, han- 
dled in HTTPsync with the TDIFFLIMIT 
macro. Under MS-DOS there are no file 
mode bits for groups and other classes. 
These are handled with the MODMASK 
and GENMODMASK macros. See the 
HTTPsync code (available electronically) 
for details. 


Reusable Routines 

In early versions of HTTPsync, I used 
HTTP/1.0 transfers (one request per con- 
nection) only. Traffic and performance 
studies showed that using persistent 
HTTP/1.1 connections would provide sig- 
nificant improvement. The routines with 
names beginning with “HTTPaccess_” im- 


plement DNS lookup, requests through 
proxies, and persistent HTTP/1.1 con- 














nections with fallback to HTTP/1.0 if prob- 
lems are detected. These functions will be 
useful in other projects. Listing Two shows 
the use of these functions to make multi- 
ple requests to a server. In summary, a 
call to HTTPaccess_OpenConn() is fol- 
lowed by a call to H7TPaccess_Retrieve() 
for each request. 

HTTPsync includes the source code for 
two functions not provided in all standard 
libraries. The reusable software directory 
at http://www.mibsoftware.com/reuse/ 
was used to locate and include source 
code for these functions. HTTPsync needs 
to parse and convert numbers in base 10 
(dates and sizes), base 8 (file modes), and 
base 16 (HTTP/1.1 chunked-transfer en- 
coding). The “Integer Conversion” topic 
of the directory led to strtol() sources from 
the FreeBSD cvsweb, which converts any 
base from 2 to 36. Also, there is no 
portable and reliable system call to con- 
vert a GMT date to a time_t. The mktime() 
function is close, but does not handle time 
zones deterministically. The “Calendar and 
Time” topic listed in tm_to_time.c from 
the comp.sources.unix archive, which was 
modified slightly to remove time zone han- 
dling. 


The HTTPsync Packing List 

You generate an HTTPsync packing list 
with the -m command-line parameter, 
providing a list of files on the standard 
input, one per line. There are four types 
of lines in an HTTPsync packing list, de- 
termined by the initial characters starting 
the line. 


e Lines beginning with “.” specify a file 
or directory; see Example 1. The fields 
of the line in order are file path @which 
must begin with “./”), file size, file date 
(day of week, day, month name, four- 
digit year, hh:mm:ss GMT), and the oc- 
tal mode. All file paths are relative to 
the current directory. They may include 
subdirectories that will be created au- 
tomatically, but must not contain the 
character sequence “..”, or white space. 
The “..” restriction is enforced on the 
client side to prevent a malicious pack- 
ing list from writing or deleting any files 
outside the current directory hierarchy. 
HTTPsynce runs as an unprivileged util- 
ity, so file ownership will be the same 
as the process owner. The file mode 
bits are masked to prevent the installa- 
tion of symbolic links and setUID exe- 
cutables. 

e Lines beginning with “O” specify obso- 
lete files or directories. These files will 
be removed from the local collection, if 
they exist. When creating a packing list, 
it is important to list all files that have 
ever been made obsolete. HTTPsync 
with the —m parameter will write an “O” 
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(continued from page 54) 
line for files that are named, but do 
not exist. 

e Lines beginning with “R” modify the 
root URL used for the HTTP requests. 
The current directory used to store lo- 
cal files is not changed. This permits 
URLs for packing lists generated from 
CGls to be separated from the file re- 
quests. CGI generated packing lists per- 
mit access control, authentication, and 
other customization as necessary. 
There may be only one “R” line per 
packing list. 

e Lines beginning with “#” are ignored as 
comments, except for a line beginning 
with the sequence “#—#httpsync.” This 
line specifies the version of the packing 
list format. The version number pro- 
vided in the packing list is checked to 
prevent older HTTPsync software from 
trying to process future formats. 


HTTPsync in Action 

My first application of HTTPsyne was to 
provide an alternate method of obtaining 
the InterNetNews development tree, a col- 
lection of approximately 500 files totaling 
more than 4 MB uncompressed (1 MB 
when compressed). The tree was already 





Listing One 


/* Macros and environment for portable sockets code 


* 1. Code is written using readsocket, writesocket, closesocket, 
* INVALID_SOCKET, SOCKET_ERROR, SOCKET, and INADDR_NONE 


2. Always use SocketStartup() and SocketCleanup () 


* 3. Conditional includes and definitions for those macros 
* allow operation under Windows and BSD-style sockets. 


*/ 
#ifdef WIN32 /* Windows systems */ 


#include <winsock.h> 

#include <io.h> 

#define readsocket(a,b,c) recv(a,b,c,@) 
#define writesocket(a,b,c) send(a,b,c,@) 


/* closesocket() does not need a macro. INVALID_SOCKET, SOCKET_ERROR, 


available to those with CVSup clients and 
via FTP as compressed archives. 

Over a 10-week period beginning Au- 
gust 11, 1998, HTTPsync was used to syn- 
chronize to the INN 2.2 development tree 
a total of 359 times. For that time period, 


HTTPsync compiles 
cleanly on WinSock 
and BSD systems 





running HTTPsync once per day resulted 
in an average transfer of 160 KB, which 
includes the 26 KB packing list, which is 
always transferred. With daily incremen- 


tal updates, HTTPsync transferred 84 per- 





cent less data than FTP of compressed 
archives would have. 


Conclusion a 
The portable design of HTTPsync and 
use of basic standards allow use in a 
much wider range of situations than oth- 
er incremental update distribution sys- 
tems. Individual software developers can 
make source code collections available 
as individual files on standard web 
servers, and HTTPsync allows incre- 
mental synchronization. With personal 
web servers for PC-level systems, you 
can keep a master collection on a small 
or home machine, and efficiently trans- 
fer it to target systems. The implemen- 
tation itself can be reused in writing oth- 
er HTTP/1.1 clients for BSD and WinSock 
systems. Some of the features that may 
be included in future versions of HTTP- 
sync are data compression, using HTTP 
Authentication for requests, partial file 
transfers (only the changed parts of files), 
and “pipelined” HTTP/1.1 (requesting 
the next file before the current transfer 
is complete). 
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char *pszReason; /* Gets error return of the form X-NNN-Message */ 
char buf[8192]; /* Retrieve fails if all headers don't fit in this buffer */ 


FILE *f£DEST; 


*/ 
theHTA.cAttempt = 9; 


SocketStartup(); /* Needed once per application. */ 
HTTPaccess_Initialize(&theHTA, pszProxy, pszHost, nPort, buf, sizeof(buf)) ; 


/* Once initialized, theHTA can be used to make more than one request. 
* This example shows just one request, with retries. 


while(1) { /* Will loop and retry until success, or too many attempts */ 


/* Initialize for read */ 


fDEST = fopen(pszDest,"wb") ; 


if (!fDEST) { 


fprintf(stderr, "Terminated. Could not open %s for writing\n",pszDest) ; 


exit(-1); 


* SOCKET, and INADDR_NONE are already defined in winsock.h 


* / 
WSADATA libmibWSAdata; 


#define SocketStartup() if (WSAStartup(@x101,&libmibWSAdata)) exit(-1) 


#define SocketCleanup() WSACleanup () 
#else /* Unix-style systems */ 


#include <sys/socket.h> 
#include <netinet/in.h> 
#include <arpa/inet.h> 
#include <netdb.h> 


+#define readsocket read 

#define writesocket write 

#define closesocket close 

#define SocketStartup () 

#define SocketCleanup () 

#define INVALID_SOCKET -1 

#define SOCKET_ERROR -1 

#define SOCKET int 

/* define INADDR_NONE if not already */ 
#ifndef INADDR_NONE 

#define INADDR_NONE ((unsigned long) -1) 
#endif 


#endif 


Listing Two 


pszReason = HTTPaccess_Retrieve(&theHTA, pszURI, fnWriteFile, fDEST); 


fclose(fDEST) ; 


if (!pszReason) break; /* success */ 


if (atoi(pszReason+2)!=3) { 
fprintf(stderr, "Terminated. Could not transfer %s\n",pszDest) ; 


exit (=1); 
} 
/* loop to retry */ 


closesocket (theHTA.s); 


SocketCleanup(); /* Needed once per application. */ 


/* Example use of HTTPaccess_ subroutines to retrieve via HTTP/1.1. 
* This code supports automatic retries and fallback to HTTP/1.0 


*/ 


char *pszProxy = 9; /* Set to hostname if proxy should be used */ 


char *pszHost = "host.domain.com"; 

int nPort = 80; /* Default HTTP port */ 
char *pszURI = "/source/packing.1st"; 
char *pszDest = "./packing.1st"; 


struct HTTPaccess_s theHTA; /* Holds state across multiple requests */ 


56 


DDJ 


Dr. Dobb’s Journal, July 1999 





Something every 
application developer needs. 


Caché, the post-relational database, 


gives developers something that PED 
relational databases can’t. We call it a LICK | 


to speed up 














“License to Speed”. ¢ you 
a y Entitcation development 
Caché is so fast we’ve had customers and performance 


InterSystems sy 


4 cc CACHE. 


post-Relational Database 


get up to a 20x boost in SQL performance 





after switching their database. And without 


touching a single line of application code. 





But Caché gives you more than 
lightning-fast speed. All this is made possible by Caché's 
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Caché comes from 
InterSystems, the leader in 
high-performance database 
systems, with over 2,000,000 
licensed users worldwide and 20 
years of database experience. 

If you want to speed 
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Portability for 
heterogeneous hosts 








Tilo Christ 


alm computing devices— the Palm- 

Pilot, Palm III, and their cousins — 

are designed to exchange data with 

stationary host machines. Unfortu- 
nately, Palm’s desktop software for han- 
dling the data transfer runs only on Win- 
dows and Macintosh. You can develop your 
own custom synchronization code (called 
“conduits”) using Palm’s Conduit Devel- 
opment Kit, which interacts with Palm’s 
HotSync Manager (HSM). However, the 
HSM itself has several weaknesses: 


e It will not run as a Windows NT service. 

e It offers poor support for multiple si- 
multaneous connections. 

e There are no management features for 
multiple PalmPilots. 

e It is tied to the Windows platform. 


To address these weaknesses, I wrote 
the SyncBuilder framework. It lets you 
write Java applications that can commu- 
nicate with an arbitrary number of Palm- 
Pilots and can be deployed on any host 
platform. SyncBuilder works indepen- 
dently of the HotSync manager, supports 
the use of Network HotSync, and facili- 
tates code sharing and reuse by offering 
a clearly defined interface for the syn- 
chronization modules. 


Tilo is a student of medical informatics in 
Heilbronn and Heidelberg, Germany. He 
also works as a freelancer for Siemens Med, 
and can be reached at tilo.christ@online.de. 
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SyncBuilder (available electronically from 
DDJ, see “Resource Center,” page 5, and at 
http://come.to/SyncBuilder) is built on top 
of Kenneth Albanowski’s Pilot-Link package 
(ftp://ryeham.ee.ryerson.ca/pub/PalmOS/), 
a freely available (under the Library GNU 
Public License) package for building syn- 
chronization code on UNIX platforms. A 
port to Win9x/NT is available at http:// 
lemming.stud.fh-heilbronn.de/~christ/ 
pilot-xfer/. SyncBuilder derives from the 
Pilot-Link Java binding, and is also available 


under the LGPL. Because some of Sync- 
Builder still relies on Pilot-Link, it has limi- 
tations on platforms other than UNIX and 
Windows 9x/NT. However, there are plen- 
ty of things that SyncBuilder can do on all 
platforms, and the examples in this article 
have been designed to work on all plat- 
forms. Nevertheless, I am working hard to 
remove the existing limitations, one by one. 


PalmPilot Basics 

Before you can synchronize with the 
PalmPilot, you need to have a rough idea 
of what kind of data entities you may find 


Java, Synchronization, 
the PalmPilot 





on this gizmo. What follows is a quick, al- 
beit incomplete, rundown: 


e Databases. Each application on the de- 
vice has zero or more databases that 
contain a header with some information 
(date of creation, number of records, 
and so on), variable-length records that 
contain the actual data, a Creator ID 
(CID), a type, and a name. The CID is 
used to link the database to an appli- 
cation. The CID, name, and type can be 
used to identify the database. 

Records. Each database contains records. 
The records store the content of the 
database. They are of arbitrary length, 
and they contain their own headers that 
contain information about the record (cat- 
egory, modified, deleted, and the like). 
Application information, which is linked 
to an application’s database. Every ap- 
plication can have as many application 
information blocks as it has databases. 
These information blocks are typically 
used to store information about the 
database categories. 

Preferences. Each application may have 
arbitrary preferences that are associat- 
ed with that application as a whole. 
User information, card information, and 
network HotSync information. These are 
various items that can be retrieved from 
the device. They are global and not tied 
to a specific app. 


Desktop Link Protocol 

The PalmPilot and host communicate 
through the Desktop Link Protocol (DLP). 
The PalmPilot initiates the connection, us- 
ing either a direct serial cable or modem 
to reach the host. After an initial hand- 
shake, the host takes control. Using DLP, 
the host can order the PalmPilot to find, 
retrieve, and manipulate all of the afore- 
mentioned data entities. When the host is 
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(continued from page 58) Although DLP is a datagram-oriented 
finished, it informs the PalmPilot, and both protocol, the PalmPilot only uses it over 
parties will disconnect. reliable streaming connections (either an 





error-correcting serial connection or 
TCP/IP). The serial protocol stack consists 
of three layers and an extra mode for the 
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negotiation of interface parameters; see 
Figure 1. 

DLP is based on a simple request/re- 
sponse pattern, with the host sending the 
requests. The host assembles a datagram, 
which consists of a command code and a 
block of parameters. It then sends this 
datagram to the PalmPilot. The PalmPilot 
replies with a response datagram that con- 
tains a response code and a block of re- 
turn values. The layout of these datagrams 
is illustrated in Figures 2, 3, and 4. 

For example, if the host wanted to read 
a record from an open database, it would 
construct a datagram that contained the 
command code for “Read Record by In- 
dex,” the database handle, and the record 
index in the parameter block. The PalmPi- 
lot would reply with a datagram that con- 
tained a response code indicating successful 
execution, and a return value with a ver- 
batim binary copy of the record’s contents. 

If the host wanted to write a record to 
the PalmPilot, it would place the data and 
the database handle in the parameter 
block, and the command code would be 
set to “Write Record.” The response data- 


Figure 1: Serial protocol stack consisting of three layers and an extra mode for gram in these cases is very short, because 


the negotiation of interface parameters. 


it only contains the response code and 
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the unique ID of the newly created record. 
Similar read and write operations are avail- 
able for all the data entities on the PalmPi- 
lot. Some entities can also be looked up 
in various ways. The database records can 
be found through their index, through 
their unique ID, through their category 
(PalmOS lets you place records into 15 
user-defined categories), and through their 
state of modification. 

As the developer, you do not have to 
concern yourself with the internals of the 
DLP protocol. An array of easy to use 
methods will conceal all the complexity 
from you. These methods will do all the 
conversion tasks between Java data types 
and the byte-arrays of the datagrams for 
you. They also relieve you from the bur- 
den of having to remember the command 
codes of the DLP protocol. 


Conduits 
Conduits are dynamically loadable modules 
that tell the HotSync Manager software how 
to synchronize a specific PalmPilot app’s 
data with a specific desktop app. Conduits 
use an API exposed by the HotSync Man- 
ager to handle the communications. 
Because it can be tedious to operate 
on this low level, Palm sells the Conduit 
Development Kit (CDK), a C++ frame- 
work that encapsulates most of the syn- 


chronization logic and all of the neces- 
sary calls to the HotSync Manager. This 
framework contains a set of classes that 
can scan a database on the PalmPilot and 
retrieve the state of modification of all 
the records. You have to implement code 
that creates a similar list for the mirror 
database (the database of the desktop 
application that is supposed to be syn- 
chronized with the PalmPilot application). 
The C++ framework can then compare 
all of the states and decide how to up- 
date both databases. 

You have to implement helper code that 
can translate single database records from 
the PalmPilot application’s format to the mir- 
ror database’s format. This process is de- 
scribed in an article by Stu Slack, published 
in PDA Developer magazine (September/ 
October 1996, also available at http:// 
www.wweg.com/published/conduit.htm). 

Palm Computing has also released CDK 
Java, a similar development kit for Java. 
However, this kit is still tied to the Win- 





dows platform and needs to cooperate 
with the HSM, which means it inherits all 
of its weaknesses. 


SyncBuilder 

SyncBuilder, on the other hand, supports 
all of the previously mentioned data enti- 
ties, and communicates through either a 
direct serial cable, or through Network 
HotSync. Network HotSync works on all 
platforms, but serial connectivity is only 
supported on Windows 9x/NT and UNIX 
machines. Modem HotSync is not sup- 
ported at all; you can get identical results 
using Network HotSync. 

The framework began as a set of Java 
classes that encapsulated the native UNIX 
code of the Pilot-Link library. While this 
gave me a quick, working implementation 
on my Linux box, it restricted me to UNIX 
platforms. The Pilot-Link code was also not 
reentrant, which made it hard to use in con- 
junction with the multithreaded Java appli- 
cations. I therefore decided to reimplement 





Figure 2: Datagram #1. 
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all the functionality of the Pilot-Link library 
in Java, with an emphasis on networking 
through TCP/IP and on full thread safety. 
This conversion is not complete yet, but 
the following parts are done: 


¢ The ability to use Network HotSync. 

e Support for all operations of the DLP 
protocol. 

¢ Special support for some of the 
PalmPilot’s built-in applications (Memo 
Pad, ToDo list, Datebook, Mail, and 
Address Book). 

e Support for PalmPilot database files 
(.PRC and .PDB files). 


Only synchronization through a direct 
serial cable still relies on native code. 

The design of the framework is cen- 
tered around the packages com.sync- 
builder.sync, which contains classes for 
establishing connections between the host 
and the PalmPilot, and com.syncbuilder 
storage, which contains classes that mir- 
ror the data entities. 

The com.syncbuildersync.DIp-class links 
these two packages by encapsulating the 
functionality of DLP. Every time you es- 
tablish a connection with the PalmPilot, 
you can obtain an instance of Dip. The 
Dip class’s methods take objects from the 
storage package as their parameters, and 
return objects from the same package. 
Many methods in the Dip class open or 
create databases. These methods give you 
com.syncbuilder.storage.Database objects 
as the return value. The Database class 
has a set of methods to read/write records, 
which delegate their work to nonpublic 
methods of the Dip class. This might not 
be a clean approach, but it is usable. 

Other packages include com.syncbuilder 
device, which offers wrappers for the 
global data entities (UserInfo, CardInfo, Net- 
SyncInfo), and com.syncbuilder.util, which 
offers various utility classes (packing/un- 
packing of data structures, and so on). 


The Database Class 
The com.syncbuilder.storage.Database 
class is one of the key classes in Sync- 
Builder. You will not be able to develop 
synchronization applications without a 
working knowledge of it. Database is also 
one of the keys to developing reusable 
code for custom PalmPilot applications. 
The Dip object’s openDB() method re- 
turns a Database object, which represents 
an opened database. This object gives you 





Figure 3: Datagram #2. 
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access to the records and properties of 
the database. You can also retrieve the 
Application Information block of the 
database, which is represented by the App- 
Block class. The subclass CategoryApp- 
Block can store the names of up to 15 
database categories within the Application 
Information block. This ability is used by 
most of the built-in applications. 

Most of the methods in these classes 
(such as getRecord() and putRecord()) are 
self explanatory. Their parameters require 
an understanding of the ways in which the 
Palm devices organize their data. Figure 5 
is an Entity-Relationship (ER) diagram of 
the Palm device. The class diagram in Fig- 
ure 6 is organized similar to the ER dia- 
gram and should help you determine how 
the classes of the framework map to the 
entities on the Palm device. 

Most PalmPilot applications use a dif- 
ferent format for the data layout of their 
records, and contain application informa- 
tion that is different from that of any oth- 
er application. SyncBuilder accommodates 
these differences by using specializations 
(inheritance) of the relevant classes. If you 
wish to develop support for a proprietary 
application, you will have to create spe- 
cializations of three classes: Databaselmpl, 
Record, and AppBlock. You might want to 
look at the subpackages in com.sync- 
builder.storage (generic, appointment, 
ToDo, and the like). 

Database uses Databaselmpl, which im- 
plements the methods that are different 
between different databases. Database- 
Impl’s main responsibility is to return the 
right specializations of Record and App- 
Block. For example, the getRecord() 
method of the Database class specifies 
Record as the return parameter, but the 
type that is actually returned is a special- 
ization of Record. The Database class del- 
egates the creation of the right special- 
izations to Databaselmpl. 1 separated 
Databaselmpl from Database to make it 
more reusable. I am already reusing it for 
a class that deals with in-memory databas- 
es (com.syncbuilder.storage.Memory- 
Database). 

When you obtain a Database object 
through the Dip, you specify the Database- 
Impl you wish to use as a parameter to the 
openDB() method. Record is responsible 
for properly parsing and constructing the 
internal representation of a database’s 
records. Your own specialization needs to 
implement the pack() and unpack() meth- 
ods. You might also wish to add accessor 
methods for the record’s attributes. pack() 
is responsible for packing the record's at- 
tributes into the application’s native byte 
structure. The native structure and its mean- 
ing are defined by the application that runs 
on the Palm device. You should derive 
meaningful attributes from that structure and 


Dr. Dobb’s Journal, July 1999 


write a conversion routine. The umpack() 
method does the exact opposite. It unpacks 
the application’s native byte structure into 








the record’s attributes. The methods in 
com.syncbuilder.util.PackUtils can help you 
write pack() and unpack() methods. 


Figure 6: Class diagram organized similar to the ER diagram. 














Implementing AppBlock is only neces- 
sary when the Palm application wishes to 
use application information blocks. The 
methods of this class are comparable to 
those of the Record class. This is not sur- 
prising, because they both inherit from 
the same parent class (com.syncbuilder 
storage.Block). You will have to imple- 
ment the pack() and unpack() methods 
again. If you wish to support database cat- 
egories, like the built-in applications do, 
you can let your AppBlock class inherit 
from com.syncbuilder.storage.Catego- 
ryAppBlock instead of com.syncbuilder 
storage. AppBlock. CategoryAppBlock al- 
ready contains helpful support methods 
for parsing and creating categories. 

You can use these classes right away to 
do simple data retrieval from your newly 
supported application. If you wish to do 
two-way synchronization, you need to de- 
termine the synchronization logic, and 
then write a specialization of the Sync- 
Handler class. Listing Two shows the ba- 
sic layout of a synchronization special- 
ization and explains how all the parts fit 
together to form a synchronization appli- 
cation. The SyncHandler’s init() method 
needs to reserve all the resources that are 
required by the synchronization proce- 
dures. The service() method is invoked 
for every Palm device that connects to 
your host. It provides you with a Dip ob- 
ject and thus allows you to open a 
database and do synchronization work. 
Finally, the destroy() method is responsi- 
ble for freeing up all resources when the 
synchronization application is shut down. 


Examples 
Listing One shows the typical structure of 
a simple synchronization application, 
which reads information from the Pilot 
and adds.a nonsensical datebook entry. 
The application first determines how the 
user wants to synchronize (serial or net- 
work), then sets up an instance of Server- 
Socket and invokes the ServerSocket’s ac- 
cept() method. This is a blocking method 
that returns a Link object when it has suc- 
cessfully established a connection with a 
PalmPilot. The Zink object’s getDip() 
method returns a Dip object, which gives 
you access to all the functionality of the 
DLP protocol. SyncBuilder comes with spe- 
cial support for the PalmPilot’s built-in ap- 
plications. For example, there is a special 
Databaselmpl class that supports the Date- 
book application, and you can feed that 
Databaselmpl class to the Dip’s openDB() 
method to open the Datebook’s database. 
If you run this example through a seri- 
al cable, you should not wait longer than 
a few seconds before pressing Return; oth- 
erwise, the Pilot will consider the con- 
nection dead. Network HotSync does not 
have this limitation. 
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Listing Two shows you how to write a 
simple program that can serve many PalmPi- 
lots simultaneously through the Network 
HotSync protocol. Figure 7 illustrates the 
control flow for this program. The key ele- 
ment here is the SyncServer class, a multi- 
threaded server that takes care of connec- 
tion management. It delegates each incoming 
connection to a SyncHandler object. The 
SyncHandler object gets a Link to the con- 
nected device and can execute all DLP op- 
erations through this Zink. You will have to 
provide your own implementation of Syrc- 
Handler to do anything meaningful. The im- 
plementation in Listing Two is called Sim- 
DleHandler. It is important to understand that 
all connections are handled simultaneously 
by the same SyncHandler object. This rais- 
es the same synchronization issues as Java- 
Soft’s Servlet technology, but it can general- 
ly be handled easily. 

The SyncHandler interface is one of the 
keys to software reuse in this framework 
(the other one is the ability to reuse im- 
plementations of Databaselmpl, Record, 








Figure 7: Flow of control for example program. 


and AppBlock). You can encapsulate all of 
your synchronization strategy into a Syn- 
CHandler, and then share it with others. 
You can also use a SyncHandler either with 
single-threaded code, or with the Sync- 
Server. You can combine SyncHandlers by 
chaining them. In that scenario, one Syn- 
cHandler would be used to invoke the ser- 
vice() method of other SyncHandlers, per- 
haps based on the identity of the PalmPilot. 


Conclusion 

SyncBuilder is an open and continuing ef- 
fort to develop a powerful framework for 
all of your synchronization needs. It is us- 
able now and will be better in the future. 
Planned additions include user-management 
capabilities, configurable error-handling, and 
ready-to-use SyncHandlers for some of the 
more popular applications (e-mail, Satellite 
Forms). I appreciate all comments, success 
stories, and contributions of code. 


DDJ 
(Listings begin on page 66.) 
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Listing One 


/* samplecode/dlptest. java: 

* Copyright (C) 1998, Tilo Christ 

* This is free software, licensed under the GNU Public License V2. 
* See the file COPYING for details. 

*/ dlp.endHotSync(); 


/* $Id: dlptest.java,v 1.1 1998/09/16 08:57:51 christ Exp $ */ 


System.out.println("The record should have been added 

now with UID " + record.getID().getValue() + "."); 
System.out.println("Press <RETURN> to continue..."); 
com.syncbuilder.util.Util.readLine() ; 


catch(Throwable t) 


import com.syncbuilder.sync.*; { 
import com.syncbuilder.storage.*; t.printStackTrace() ; 
import com.syncbuilder.device.*; } 
} 
/** A test for the PalmOS DLP-functionality. This is also a sanity check } 


for the new Pure Java Implementation of the DLP. 
* @author Tilo Christ 


*/ e ° 
public class dlptest Listing Two 
{ 
public static void main(String[] args) /* samplecode/SyncServerTest. java: 
{ * Copyright (C) 1998, Tilo Christ 
try * This is free software, licensed under the GNU Public License V2. 
{ * See the file COPYING for details. 
String port = null; 
System.out.print("Port to use (\".\" means */ 


Network HotSync) [/dev/pilot]? "); /* $Id$ */ 
System.out.flush() ; 

port = com.syncbuilder.util.Util.readLine() ; 
if (port.equals("")) 


port = "/dev/pilot"; 


import com.syncbuilder.sync.*; 
import com.syncbuilder.device.*; 


/** Demonstrates use of the com.syncbuilder.sync.SyncServer-class. 
* Will not work through PalmPilot's regular HotSync app; only through 


if (port.equals(".")) 
{ * the Network HotSync app (obtain separately from Palm Computing) . 


Socket. setSocketFactory( new NetworkHSSocketImplFactory() ); 
System.out.println("Initiate Network HotSync now."); 


* @author Tilo Christ 


s/ 


public class SyncServerTest 


else if 
{ public static void main(String[] args) 
System.out.println("Please hit the HotSync button now."); { 
try 
ServerSocket ssock = new ServerSocket (port) ; { 
Link link = ssock.accept(); // Create a ServerSocket for use with Network HotSync. 
Dlp dlp = link.getD1p(); Socket. setSocketFactory( new NetworkHSSocketImplFactory() ); 
System.out.println("The connection-protocol has a version of: " ServerSocket ssock = new ServerSocket (null) ; 
+ link. getProtocolVersion()); 
System.out.println("Information about the HotSync user will"); // Create the SynceServer from the ServerSocket. The SyncServer 
System.out.println("be read from your device"); // will serve all clients using SimpleHandler (see the class 
System.out.println("as soon as you start the action."); // SimpleHandler below). SimpleHandler will mostly print diagnostic 
System.out.println("Press <RETURN> to start the action..."); // messages and read the UserInfo from the device. 
com.syncbuilder.util.Util.readLine() ; SyncServer sync_server = new SyncServer(ssock, new SimpleHandler()); 
System.err.println("Initiate the Network HotSync procedures now."); 
UserInfo uinfo = dlp.getUserInfo(); // The SyncServer starts running NOW! 
System.out.println( uinfo.toString() ); sync_server.start(); 
System.err.println("Press <RETURN> to stop the service"); 
System.out.println("The user-info should have been displayed now."); com.syncbuilder.util.Util.readLine() ; 
System.out.println("Press <RETURN> to continue..."); // The SyncServer is shut down 
com.syncbuilder.util.Util.readLine() ; sync_server.stop(); 
} 
System.out.println("The message on your PalmOS device should"); catch(Throwable t) 
System.out.println("switch from ‘Identifying User' { 
to 'Synchronizing'") ; t.printStackTrace() ; 
System.out.println("as soon as you start the action."); } 
System.out.println("Press <RETURN> to start the action..."); } 
com.syncbuilder.util.Util.readLine(); } 


dlp.switchMessage() ; 


System.out.println("The message should have switched now."); 
System.out.println("Press <RETURN> to continue..."); 
com.syncbuilder.util.Util.readLine() ; 


/** Non-public class. Used by SyncServer to handle incoming connections. */ 
class SimpleHandler 


{ 


implements com.syncbuilder.sync.SyncHandler 


/** Invoked one time at start-up */ 
public void init() 


System.out.println("The message on your PalmOS device should"); { 
System.out.println("switch from 'Synchronizing' to 

‘Synchronizing Datebook'") ; System.err.println("SimpleHandler.init()"); 
System.out.println("as soon as you start the action."); } 


System.out.println("Press <RETURN> to start the action..."); 
com.syncbuilder.util.Util.readLine() ; 


/** Invoked every time a device connects */ 
public void service(Link link) 
throws Exception 


Database dbase = dlp.openStockDB { 

(new com.syncbuilder.storage.appointment.DatabaseImpl()); System.err.println("SimpleHandler.service() with " 
System.out.println("The message should have switched now."); + link.toString() ); 
System.out.println("Press <RETURN> to continue..."); Dlp dlp = link.getD1p(); 
com. syncbuilder.util.Util.readLine(); // Do it ten times, so it takes more time... 

for (int i=0; i < 10; i++) 
System.out.printin("All " + dbase.getRecordCount() + " { 

entries from your datebook will be read and displayed") ; UserInfo uinfo = dlp.getUserInfo(); 
System.out.println("as soon as you start the action."); System.err.println( uinfo.toString() ); 
System.out.println("Press <RETURN> to start the action..."); } 
com.syncbuilder.util.Util.readLine() ; dlp.endHotSync() ; 

} 


for (int i = @:; it+) 


/** Invoked one time at shutdown */ 


{ public void destroy() 
Record rec = dbase.getRecord (i) ; { 
if (rec == null) System.err.println("SimpleHandler.destroy()"); 
break; } 
System.out.println( rec.toString() ); 5 
} 


System.out.println("The records should have been printed now."); 
System.out.println("Press <RETURN> to continue..."); 
com.syncbuilder.util.Util.readLine() ; 


System.out.println("A test entry will be added to 

your datebook at the current date"); 
System.out.println("as soon as you start the action."); 
System.out.println("Press <RETURN> to start the action..."); 
com.syncbuilder.util.Util.readLine() ; 


com.syncbuilder.storage.Record record = dbase.createRecord(); 

((com. syncbuilder.storage.appointment.Record) record) .description = 
"Dinner at the White House"; 

dbase. putRecord (record) ; 


DDJ 
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he electrical appliance industry is 

rapidly moving into the world of elec- 

tronic controls that have enough in- 

telligence to monitor and modify sys- 
tem behavior. But while the technology is 
readily available, the barrier to wide- 
spread implementation of intelligent con- 
trols is cost effectiveness, which adds to 
the price of household and other electri- 
cal appliances and devices. 

One way of reducing costs is to com- 
bine electromechanical and software con- 
trol. Once software and electronics are im- 
plemented in an appliance, you then need 
communication systems so that sensors 
can talk to controllers. Niche Area Net- 
works (NAN), based on serial communi- 
cation with embedded protocols, are start- 
ing to fill this need. In this article, I'll 
introduce “SimpleChat,” one such NAN 
communication protocol that’s designed 
for applications where cost efficiency is 
more important than very high data rates. 


Jaromir is a senior staff engineer in Mo- 
torola’s Roznov (Czech Republic) Systems 
Application Laboratory. He can be con- 
tacted at r28107@email.sps.mot.com. 


68 






The SimpleChat protocol can be support- 
ed by all types of low-end microcon- 
trollers (with built-in UART) that support 
9-bit transmission, such as Motorola’s 
68HC05/HC08 family. SimpleChat reference 
designs, for instance, have been created for 
AC inductance motor drives (using the 
MC68HCO8MP16 or MR24), temperature sen- 
sors (using the MC68HCO0S5JJ7), air condi- 
tioners, and the like. 


testes. G27 


SimpleChat Overview 
As Figure 1 illustrates, SimpleChat systems 
consist of Master, Slave, and Peer nodes. 
Peer nodes can run in Master or Slave 
mode (the default for Peer node). Master 
and Peer nodes can access the network 
at any time to perform communication. 
Slave nodes do not own the right to ini- 
tiate communication. Master nodes can re- 
quest Slave nodes to send information 
back to the Master. Because of the soft- 





ware SCI implementation specification, 
Slaves can be implemented on microcon- 
trollers without UART. 

Communication between nodes is via 
Push/Pull— the Master sends the Push 
field of the message and the addressed 
Slave responds with the Pull field. A half- 
duplex transmission performs this com- 
munication. The SimpleChat system allows 
Single Master or Multiple Master network 
configurations. Any node in a network 
can broadcast an emergency notification 
and any Master can simultaneously con- 
trol a group of Slaves. 

The SimpleChat protocol is based on 
the Open Systems Interconnect (OSI) 
seven-layer model; see Figure 2. Sim- 
pleChat addresses layers 1 (Physical) and 
2 (Data Link). The Data Link layer is di- 
vided into three sublayers— the Logical 
Link Control (LLC), Upper Media Access 
Control (UMAC), and Lower Media Access 
Control (LMAC). LLC and UMAC are typ- 
ically implemented in software. The LMAC 
is usually based on an SCI (UART) and 
simple timer. 

Devices connected to the SimpleChat bus 
use a single message format. Figure 3 il- 
lustrates the general composition of Sim- 
pleChat messages (as they appear on the 
bus). An IDLE symbol separates any mes- 
sage on the bus from other messages. Each 
message consists of two major fields — Push 
and Pull. The Push field contains informa- 
tion sent from the Master to the Slave. The 
Pull field contains information sent from the 
Slave to the Master. A passive bus period 
that is shorter than an IDLE symbol is 
known as an Inter-Frame Separator (IFS) 
and separates Push/Pull fields. 
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(continued from page 68) 

The first frame of a Push/Pull field is 
always an Address frame. Following Ad- 
dress frame 0, one or more Data frames 
are present. The last frame of a Push/Pull 
field is always a Data frame containing a 
checksum of all of the previous frames in 
the field. The protocol uses a simple 8-bit 
arithmetic checksum. An IFS also sepa- 
rates frames within a Push/Pull field. The 
SimpleChat protocol supports different 
types of messages. 


Application Messages 
Application messages (Figure 4) are 
those in which Masters or Peers convey 














Figure 1: SimpleChat network. 


OSI Layers — 






Figure 2: OSI Model. 








Figure 3: Message composition. 
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until an IDLE symbol appears on the bus. 


application information to Slaves (and 
vice versa). Since application informa- 
tion is being exchanged, and since the 
SimpleChat protocol does not define 
any of the application layer, the content 
and meaning of application messages 
are completely application dependent. 
The SimpleChat protocol merely pro- 
vides a data link for connecting the ap- 
plications. 

Using Application messages, the Mas- 
ter controls the timing of all frames with- 
in the Push field and the Slave controls 
the timing of all frames within the Pull 
field. Another message may not be sent 
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Network Messages 

Network messages (Figure 5) are one-way 
broadcasts in which Masters or Peers con- 
vey network information to all Slaves in 
the network. The SimpleChat Data Link 
generates all network messages. The ap- 
plication should never attempt to gener- 
ate them because of unpredictable con- 
sequences. 

With network messages, Masters con- 
trol the timing of all frames within the Push 
field. Another message may not be sent 
until an IDLE symbol appears on the bus. 

Addresses 254 (%11111110) and 253 
(%11111101) are reserved for network mes- 
sages and must never be used for Slave 
devices. In addition, the protocol speci- 
fies addresses 0 (%00000000) and 255 
(%11111111) as illegal. These addresses 
have higher probability of appearing ac- 
cidentally under faulty conditions, so these 
addresses must never be used for Slave 
devices either. This still leaves enough 
combinations for uniquely addressing 
Slaves. Reserved network messages (Table 
1) include: 


ILLEGALO (ILLEGALO — %00000000). 
An illegal 0 (LLEGALO) network message 
is any message that has all logic Os with- 
in the Push/Pull Header frame. 

ILLEGAL1 CLLEGAL1 — %11111111). 
An illegal 1 GLLEGAL1) network message 
is any message that has all logic 1s with- 
in the Push/Pull Header frame. This is il- 
legal because many SCIs and UARTs can 
mistake a Header frame like this for an 
IDLE symbol. It also prevents a single 
noise pulse (1-bit time during an idle bus 
condition) from being mistaken as a sin- 
gle header frame of value %11111111. 

BROADCAST (BROAD — %11111110). 
Broadcast messages are those simultane- 
ously sent to all Slaves in the network. The 
Master sends a common Push field to all 
Slaves. Depending on the broadcast mes- 
sage type, zero or one Slaves (but never 
more than one) may reply with a Pull field. 


e Sleep (SLEEP), used for the network to 
enter into SLEEP mode. 

e Wake (WAKE), used for the network to 
wake-up from SLEEP mode. 

e Synchronization (SYNC), used for 
many purposes. SimpleChat networks 
that contain devices with timebases of 
wide tolerance require periodic resyn- 

chronization. This is achieved by en- 

suring that the Master periodically 
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(continued from page 70) 
sends a special message that performs 
no data transfer and is only used by 
the Slaves for deriving timing infor- 
mation. This is the primary purpose of 
the SYNC message. The periodic ac- 
tion occurs totally within the Sim- 
pleChat Data Link, and no application 
intervention is required. 


MULTICAST MESSAGES (MULTI — 
%11111101). Multicast messages (Figure 
6) are those in which the SimpleChat Mas- 
ter conveys network information to all 
Slaves within the specified group and is a 
one-way broadcast communication. All 
Slave nodes must specify which group 
they belong to. With multicast messages, 
Masters control the timing of all frames 


within the Push field. Another message 
may not be sent until an IDLE symbol ap- 
pears on the bus. 


Network Access Control 

Since the network is a shared communi- 
cation channel, the network protocol must 
define how the channel is shared. Recall 
that the same SimpleChat node can serve 
as a Master, Slave, or Peer. Most networks 
are comprised of one Master and sever- 
al Slaves. In such a configuration, the Mas- 
ter polls each Slave periodically. When 
polled, a Slave can transmit a message. 
No potential conflict can occur on the bus 
because of the communication timing by 
the Master. However, also recall that the 
SimpleChat protocol allows for multiple 
Mastets. 
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When the bus is free, any Master or Peer 
node can start to transmit a message. A 
node that is ready to transmit a message 
must first sense if another node is cur- 
rently transmitting. If not, the first node 
can begin transmitting immediately. Pri- 
oritized messages are transmitted. If two 
or more nodes start transmitting messages 
at the same time with the same priority, 
the bus access conflict is resolved by byte- 
wise arbitration. The Master or Peer node 
with the message of highest priority to be 
transmitted gains bus access. SimpleChat 
network access control is based on the 
method used by SAE J1708, “Serial Data 
Communications Between Microcomput- 
er Systems in Heavy Duty Vehicle Appli- 
cations” (1990). 


Collision Avoidance 

Masters can begin transmitting messages 
only after an IDLE state on the bus, and 
if the bus is still free in the specific time 
window after that. The specific time win- 
dow for the collision avoidance (Tz,) is 
defined as a time window of a time du- 
ration equal to the following equation: 


Toa=T, °*MP 


where 7;, is the bit time and MP is the mes- 
sage priority (0 to 7). The bus activity de- 
tection is performed inside this 7.4, win- 
dow at a bit-wise level, using start-bit 
detection, looking for the falling edge of 
a start bit. This start-bit detection is ser- 
viced by the IRQ interrupt service routine. 
If a Master node detects bus activity with- 
in the 7., window, arbitration is lost. 


Arbitration Algorithm 

The arbitration algorithm provides a 
method for reaccessing the bus if a colli- 
sion is detected. The mechanism of arbi- 
tration guarantees that information is not 
lost. If two or more Master (Peer) nodes 
transmit messages at the same time, the 
bus access conflict is recognized by the 
bus monitoring feature of the UMAC lay- 
er. When the first bus conflict occurs, all 
Master (Peer) nodes should stop their 
transmission and wait for the predefined 
collision bus access time (T¢,,), before 
starting transmission again. The collision 
bus access time 7cp, is a time duration 
equal to the equation: 


Topa=1t+(2 > T,) *MP 


where 7c», is the collision bus access time, 
T; the IDLE time duration, 7; the bit time, 
and MP the message priority (0 to 7). 

The arbitration algorithm implements a 
sequence of events: 


1. First collision detected. 
2. Each Master (Peer) node on the bus 
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stops its transmission and then waits for 
its predefined Top,. 

3. After timeout, 7¢,,, the Master (Peer), 
tries to start its transmission again. 

4. Second collision detected. 

5. Each Master (Peer) node on the bus 
stops transmission and waits for a new- 
ly defined Teg4. The new Teg, is calcu- 
lated accordingly: 


Tega= Ti+? T° R 


where 7c-p, is the collision bus access time, 
T; the IDLE time duration, 7; the bit time, 
and R the random number (0 to 7). The 
random number is the value of the last 
three bits in the core timer of the MCU. If 
any further collision is detected, the pro- 
cedure is repeated. 


The Master Data Link Interface 

The Data Link interface has two main el- 
ements— the Data Link command/con- 
trol registers (which let the application 
program control the overall operational 
modes of the Data Link) and the data 
structures (which contain the Push fields 
to be sent and the Pull fields which are 
received). 

Figure 7 illustrates the Data Link com- 
mand register (DL_command), a RAM vari- 
able shared between the application and 
the Data Link software. Using it like a reg- 
ister greatly simplifies the programmer’s 
tasks. The contents of this register are re- 
set by issuing the Data Link reset com- 
mand DL_CMD_RESET. 

Whenever a command is written to the 
Data Link command register, the Data 
Link Busy (DL_BUSY) bit (0 = not busy, 
1 = busy) is simultaneously set by the ap- 
plication program. The DL_BUSY bit re- 
mains set until the Data Link has com- 
pleted the requested command, at which 
point it will automatically clear the 
DL_BUSY bit to indicate completion. The 
application program monitors the 
DL_BUSY bit to determine the progress 
of the requested command. In general, 
another command should not be issued 
by an application to the Data Link until 
the DL_BUSY bit has become clear. 
However, the Data Link may be reset at 
any time, without waiting for the 
DL_BUSY bit to become clear, by issu- 
ing a DL_CMD_RESET command. 

The CMD5-0 Data Link commands de- 
termine the command to be executed by 
the Data Link. Whenever the Data Link is 
working on a command, the application 
program is free to continue and does not 
have to wait for the command to be com- 
pleted. The Data Link works automatical- 
ly in the background performing the re- 
quested command, thus no further 
application intervention is necessary. The 
currently defined CMD5-0 commands are: 
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e DL_CMD_RESET, which causes the Data 
Link to stop sending further messages 
(but not SYNC messages), clears all in- 
ternal error flags, and resets the 
DL_command and DL_control registers. 
DL_CMD_SLEEP, which causes the Data 
Link to stop sending further messages 
(but not SYNC messages) and then a 
SLEEP message is broadcast to the net- 
work. This command does not place the 
Master node MCU into any power sav- 
ing mode; these are responsibilities of 
the application program. 
DL_CMD_WAKE, which causes the Data 
Link to stop sending further messages (but 
not SYNC messages), and then a WAKE 
message is broadcast to the network. 
e DL_CMD_NEXT, which causes the Data 
Link to send the next application mes- 





sage and stop sending further messages 
(but not SYNC messages). 

e DL_CMD_MULTI, which causes the Data 
Link to send a multicast message and 
stop sending further messages (but not 
SYNC messages). 


The Data Link control register, DL_con- 
trol (Figure 8), is a variable that is shared 
between the application and the Data Link 
software. Using it like a register greatly sim- 
plifies the programmer's tasks. The contents 
of this register are reset by issuing the Data 
Link reset command DL_CMD_RESET. 

The SYNC Message Enable flag 
(DL_SYNC) controls the sending of SYNC 
messages (0 = disabled, 1 = enabled) and 
lets the application control the role of 
the Master. To avoid collisions, only one 
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Figure 6: Multicast network. 
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Master in the network can be configured 
to send SYNC messages. 

Finally, the MP2-0 Message Priority bits 
determine the priority of the message to 
be sent out by the Data Link. The mes- 
sage priority value is tied with each mes- 
sage issued by the Data Link. A range from 
0 to 7 of the message priority value is de- 
fined, then just the lower three bits of the 
DL_control register are used. The message 
priority 0 is the highest priority. 


Data Structures 

Data Link control software can use sim- 
ple (optimized for minimal RAM usage) 
or complex data structures. In either case, 
the two fundamental elements of Data 
Link data structures are a single Push and 
single Pull buffer, both of which reside 
in RAM. These buffers are a few bytes of 
RAM that are shared between the appli- 
cation and the Data Link software. The 
Push buffer (Figure 9) contains the in- 
formation that is to be sent in the Push 
field of message from the Master to the 
Slave. The Pull buffer (Figure 10) contains 
the information that is received from the 
Pull field of the message from the Slave 
to the Master. 

The first byte of the Push/Pull buffers 
contains the Header frame information. 
The Header frame of the Push buffer con- 
tains the address of the destined Slave and 
the Header frame of the Pull buffer con- 
tains the address from the remote Slave. 
The application can use this address in- 
formation for communication checking to 
increase the communication reliability. 

Subsequent bytes of the Push buffer 
contain the Data frames information if it 
is required by the Slave, and subsequent 
bytes of the Pull buffer contain the Data 
frame information if it is sent by the re- 
mote Slave. 


Data Link 

Command Example 

The Data Link is driven by commands. 
The application has to take care of the 
contents of the Push buffer and message 
priority value in the DL_control register 
when application and multicast commands 
are applied. The content and meaning of 
the Data frames in the Push buffer is com- 
pletely application dependent and in this 
example the following message composi- 
tion will be used. 

The Push field of the application mes- 
sage contains a Header frame with the 
destination Slave address. The first Data 
frame is an application command and the 
following Data frames are data corre- 
sponding to this command. The applica- 
tion program must fill in the Push buffer 
by the Header and the Data frames, and 
the message priority must be written into 
the DL_control register. 
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(continued from page 74) 

In this example, I'll focus on the 
DL_CMD_NEXT command, showing it 
handles application messages, basing my 
example on Motorola 68HC08 assembly 
code and presenting only the code need- 
ed for this Data Link command. 

An application message is issued by the 
DL_CMD_NEXT command. The message 
priority constant (M_PRIOR) that is tied 
with this application message is ORed into 
the DL_control variable. Next, the Data 
Link Push buffer is filled. The Slave node 
address (switch node in this example) is 
written as a Header frame into the 
DL_push_buffer base address and the ap- 
plication command (“switch on” in the ex- 
ample) is written as the first Data frame 
into the DL_push_buffer+1 storage loca- 
tion. No data is required with this com- 
mand, so the next Data frame might be a 
random value from the DL_push_buffer+2 
storage location, but a better way is to 









Figure 7: Data Link command register. 






Figure 8: Data Link control register. 






Figure 9: Data Link push buffer. 


Figure 10: Data Link pull buffer. 
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clear this memory location. When the Data 
Link Push buffer is filled, the Data Link 
DL_CMD_NEXT command is issued. The 
program in Listing One tests the DL_BUSY 
flag and waits until the command is com- 
pleted. 


Slave Data Link Interface Example 
Listing Two shows a single Push field 
buffer (DL_push_buffer), single Pull field 
buffer (DL_pull_buffer), and command 
register (DL_command) for the Data Link 
interface. The Push field of the applica- 
tion message contains a header frame with 
the Slave address, two data frames, and a 
checksum frame. The first data frame is 
an application command and the second 
data frame is data corresponding to this 
command. 

In Listing Two, the example Slave is con- 
trolled by a simple remote Master. The Slave 
is capable of turning on and off some kind 
of load. The Master sends “switch on” and 









“switch off” commands to control the Slave. 
The example can be easily extended to ex- 
ecute multiple functions. 

After initialization, the application code 
starts at the label app_loop. The applica- 
tion in the app_loop fetches the latest Push 
field that has been received by the Data 
Link. All accesses to the Push buffer are 
interlocked using the MCU’s interrupt 
mechanism. Before accessing the Push 
buffer, the application code must set the 
interrupt mask (to lock out the Data Link) 
and then must clear the interrupt mask af- 
ter the buffer has been accessed (to allow 
access by the Data Link again). This guar- 
antees coherent information exchange. 

Because the Slave already knows its own 
address, the first byte of the DL_push_buffer 
is not used by the application. The MSB of 
the DL_command location is a DL_BUSY 
flag. Whenever the Data Link has completed 
the command (received the message), it 
clears the DL_BUSY flag to indicate com- 
pletion. The application program monitors 
the DL_BUSY in the app_loop and, if it is 
zero, performs an application command. 
The application command value is read 
from the DL_push_buffer+1 storage loca- 
tion and is scaled by 4. This value is used 
as an index into a jump table (app_table). 
The index value is checked for the length 
of the jump table, to prevent jumps over the 
table. The SWI instruction is inserted into 
the app_table to get entries scaled by 4. 

This version of the software uses just two 
commands, switch_on and switch_off. 
Whenever the application has read data 
from the DL_push_buffer the DL_BUSY flag 
should be set by the application program. 


Conclusion 

Because of their small hardware re- 
quirements, UART-based networks rep- 
resent an attractive alternative in em- 
bedded distributed control. They give 
system designers flexibility in optimiz- 
ing cost-effective embedded systems. 

Niche Area Networks can be con- 
structed in a modular way. New nodes 
that communicate only among themselves 
can be attached to the network without 
knowledge of the preexisting nodes and 
without interfering with their use. 

The length of the network is so small 
that the network propagation delay can 
be neglected. All nodes see the same bit 
simultaneously, when transmitted. This 
fact increases the reliability of the network, 
as the transmitter is able to check that the 
correct value is on the bus at the time that 
it is seen by the receiver. Data integrity is 
confirmed using checksum and acknowl- 
edge methods. 


DDJ 
(Listings begin on page 78.) 
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x No action (%@0@) = 
LDA #M_PRIOR ;Get message priority FO CCGG ICR IC ki kf 2k i kk ok kok kok ok ok ok 
ORA DL_control ;Combine DL_SYNC and message priority service_000: 
STA DL_control ;Store result JMP >app_loop ;No action, resume looping.. 
LDA #SWNODE ;Get Switch node address FOGG Gok dak ki kk kok ak ok okok ok ok kok ok ok 
STA DL_push_buffer ;Store node address * SWITCH ON (%0@1) * 
LDX +SW_ON ;Get switch on command TOP tt terre ttt e ttt C SSC CeCe C PCTS CeCe rCeCecerccerreCrercerecrererceerer eee res sy 
STX DL_push_buffert1 ;Store command service_001: 
CLR DL_push_buffert2 ;No data is needed LDX #4 ;Get command to be returned 
LDA #DL_CMD_NEXT ;Get command send message CLRA ;Get data to be returned 
STA DL_command ;Issue command & start sending BSET LOAD_ON, PORTA ;Load switch on 
BRSET DL_BUSY,DL_command, * ;Wait here until command completed update_link: 
SEI ;Prevent interrupts 
oye STX DL_pull_buffert1 ;Update Pull command field 
Listing Two STA DL_pull_buffert2 ;Update Pull data field 
. CLI ;Allow interrupts 
app_loop: : 
SEI jeeevent interrupts Ss ee ee ee 
BRSET DL_BUSY,DL_command,MAIN_continue ;Branch if no new 90 pO eee eee ee 
* Push field arrived ‘ SWITCH OFF (%010) . 
LX. Di ptidh. bubfer tt ‘Heteh: ape liescion command vabue BEGGS GSS GGG GGG GCG GG GG xk kk ak ak ik kak ok 
LSLX ;Scale jump vector service_010: 
LSLX sEntries scaled by 4 LDX #2 ;Get command to be returned 
TXA ;Prepare vector for checking CLRA sak data to be returned 
SUB =START-app_table ;Check if command is in the range BCLR BORDON, EORTA iLoad switch off 
BMI command_ok ;Branch if command is OK BRA update_link ‘Update date link 
CLRX ;Clear vector if not 
command_ok: 
LDA DL_push_buffer+2 ;Fetch Push data 
BSET DL_BUSY , DL_command ;Set waiting flag 
* (cleared by new Push field arrival) 
CLI ;Allow interrupts 
JMP app_table,X ;Jump using received control DDJ 
* field as an index 
app_table: 
JMP service_000 ;Service control value %@0@ 
SWI ;Dummy byte to align jump entry 
JMP service_001 ;Service control value %@@1 
SWI ;Dummy byte to align jump entry 
JMP service_010 ;Service control value %@1@ 
SWI / ;Dummy byte to align jump entry 
START EQU 
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INTERNET PROGRAMMING 


An Architecture for 
Web Services 





Enabling reuse 
via the Web 





David Houlding 


n established vision in the distributed- 

object community involves pub- 

lishing distributed-object services 

on the Web that may be reused by 
application developers to rapidly create 
new Java applets or applications. In this 
article, I'll discuss an architecture that 
can turn this vision into reality by tak- 
ing full advantage of the synergy be- 
tween web and distributed-object sys- 
tems. This architecture also facilitates 
both the publication of distributed- 
object services on the Web, as well as 
the subsequent reuse of these web ser- 
vices by application developers to rapid- 
ly and visually create new applications. 
(In the context of this article, I define a 
“server” as a distributed object, a “ser- 
vice” as a method on a particular dis- 
tributed object, and a “web service” as 
a service that may be accessed and 
reused using only web and nondistributed- 
object technologies.) Furthermore, this 
architecture’s implementation is based 
on well-established, freely available, and 
proven technologies and development 
paradigms. 


David is an infrastructure modeler for The 


Technical Resource Connection, and can 
be contacted at david.houlding@trcinc.com. 
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Using this architecture, you can use web 
browsers to browse servers and the ser- 
vices they provide, select the service you 
wish to use, and download a proxy in the 
form of a JavaBean. This proxy encapsu- 
lates server location, protocol, licensing, 
security, and all other details associated 
with requesting a remote service. It may 
then be integrated into applications either 
visually using a JavaBean Integrated De- 
velopment Environment (IDE), or at the 


software level using any Java IDE. The ap- 
plication can then use the selected service 
by simply interacting with the proxy. The 
technologies and frameworks used to im- 
plement this architecture and illustrate this 
approach include Sun JDK 1.1.7 Chttp:// 
www.java.sun.com/), Inprise VisiBroker 
3.3 CORBA implementation (http://www 
inprise.com/), JRun 2.2 (http://www 
livesoftware.com/), and the CORBA Beans 
2.4 framework from the Technical Re- 






source Connection (http://www.trcinc 
.com/corbabeans/). An implementation of 
this architecture and interactive demo is 
available from DDJ/ (see “Resource Cen- 
ter,” page 5) and at http://www.trcinc 
.com/corbabeans/. 


An Architecture for Web Services 

The Common Object Request Broker Ar- 
chitecture (CORBA), developed by the Ob- 
ject Management Group (OMG) (http:// 
www.omg.org/), is the standard infra- 
structure for distributed-object systems. 
Proven in reliability, scalability, and ex- 
tensibility, it offers many architectural and 
implementation advantages that can be 
leveraged to rapidly create a distributed- 
object system. CORBA makes it possible 
for you to focus the development effort 
on added business value, and offers im- 
plementation and location transparency. 
This allows distributed objects to be im- 
plemented in different languages and run 
on multiple operating systems, hardware, 
or network nodes. 

The CORBA Naming Service provides 
services for CORBA clients to locate CORBA 
servers, and is organized in a tree-based 
directory structure. The root of the tree, 
the root Naming Context, may contain 
either references to servers, or subNam- 
ing Contexts. Clients can drill down 
through subNaming Contexts to locate 
the server of interest. They can then ob- 
tain an object reference that facilitates the 
location of the associated server. This is 
analogous to the Yahoo tree-based search 
engine at http://www.yahoo.com/, except 
in this case, the servers displayed are not 
web servers, but CORBA servers. The in- 
terface of a CORBA Server is defined in 
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(continued from page 80) 

an implementation language-neutral way 
using Interface Definition Language 
(IDL). For example, Listing One defines 
the IDL for a simple CORBA Inventory 
Server, and illustrates the concepts I dis- 
cuss here. The CORBA Interface Repos- 
itory is an infrastructure service that lets 
CORBA clients determine at run time the 
IDL interface of a CORBA server. Clients 
can use this interface information to dy- 
namically form and execute requests on 
the associated server using the CORBA 
Dynamic Invocation Interface (DID, com- 
municating with the CORBA server us- 
ing the standard Internet InterORB Pro- 
tocol CIOP). This CORBA functionality 
makes it particularly well suited to im- 
plementing web services over an intranet 
or the Internet. 

Figure 1 details the architecture that 
facilitates the publication and reuse of 
CORBA services over the web. To illustrate 
the roles, responsibilities, and collabora- 
tions of the components in this architec- 
ture, I'll walk through three key use-case 
scenarios. 

A server developer can publish the ser- 
vices provided by a CORBA server as web 
services by: 


1. Registering the CORBA server with the 
CORBA Naming Service. 

2. Loading the CORBA Interface Reposi- 
tory with the IDL of the CORBA serv- 
er being published. 


An application developer can reuse a 
web service by integrating it with an ap- 
plication by: 


1. Selecting a server. 

2. Selecting a service provided by the se- 
lected server. 

3. Downloading a JavaBean proxy for the 
selected service. 

4. Integrating the proxy with the applica- 
tion being developed. 


The application developer can browse 
and select a server using a web browser: 


1. You request the URL for the Naming 
Service Gateway Servlet using the 
browser. 
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Figure 1: An architecture for web services. 


2. The servlet receives this request via the 
web server and responds by contact- 
ing the CORBA Naming Service to get 
a “snapshot” of the elements in the root 
Naming Context. 

3. The servlet reformats this information 
into HTML and returns it via the web 
server to the web browser for display. 

4. The hyperlinked elements displayed 
each represent either a CORBA server 
or subNaming Context contained by the 
root Naming Context. 

5. If you then select the hyperlink for a 
subNaming Context, the display 
changes to show the elements of the 
subNaming Context in the same way 
as for the root Naming Context ex- 
plained previously. 


Using this process, you can drill down 
to the Naming Context containing the 
CORBA server that provides the services 
of interest. Selecting the hyperlinked ele- 
ment for the CORBA server results in a re- 
quest to the Naming Service Gateway 
Servlet for the interface of the selected 
server. The servlet would get this infor- 
mation from the CORBA Interface Repos- 
itory via the CORBA server, format it into 
HTML, and return it via the web server to 
the web browser for display. For exam- 
ple, selecting the Inventory Server with 
the IDL shown in Listing One, results in 
a display as in Figure 2. This display shows 
the hyperlinked signatures for each of the 
services provided by the selected Inven- 
tory Server. 

You can then select a service by click- 
ing on the hyperlink corresponding to 
that service. The Naming Service Gate- 
way Servlet responds to this request by 
first creating a JavaBean proxy to access 
the requested service, then serializing 
this bean and returning it via the web 
server to the web browser. At this point, 
the web browser prompts you to indi- 
cate a file to which you would like to 
save the serialized bean. After saving the 
bean, it may be integrated into a Java 
application to access the associated ser- 
vice. The configuration information for 
the bean is all stored in the download- 
ed bean file. This presents a significant 
advantage over configuring the bean us- 
ing software. For example, if the loca- 
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Figure 2: Naming Service Gateway 
browser view. 


tion or interface of the server associat- 
ed with the proxy bean changed over 
the lifetime of the system, the applica- 
tion developer could simply download 
a new serialized bean that reflects the 
changes. No software would need to be 
recompiled for the application to ac- 
commodate these changes. 


Integrating the JavaBean 

Proxy into a Java Application 

The bean proxy can be visually integrat- 
ed into a Java application using a JavaBean 
IDE, as illustrated in Figure 3, or at the 
software level using any Java IDE. To 
briefly illustrate the interaction between 
the application and proxy bean, integra- 
tion at the software level is illustrated in 
Listing Two. In this code snippet, the Dy- 
namicRequest proxy bean for the getltems 
service on the inventory server is first in- 
stantiated from the serialized JavaBean file 
downloaded in the previous step. The re- 
sult of the instantiation is a completely 
configured proxy bean. The input argu- 
ments for the request are then set, and the 
request is invoked. Finally, the results of the 
request are obtained through the JavaBean- 
compliant interface of the DynamicRequest 
proxy bean. For more information on the 
Dynamickequest proxy and supporting 
framework, see my article “A CORBA Bean 
Framework” (DD/, November 1998). 


Using the Web Service at Run Time 

The proxy bean collaborates with the ap- 
plication and web service at run time, as 
illustrated in Figure 4. After the proxy bean 
is instantiated, its input arguments may be 
set. The typed values of these arguments 
are cached by the proxy bean. When the 
request is invoked on the proxy bean, it 
contacts a server locator service, in this 
case the CORBA Naming Service, to get 
an object reference that allows it to locate 
the CORBA server providing the service 
it is associated with. This server location 
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(continued from page 82) 

step is only required the first time the Dy- 
namicRequest proxy bean is invoked. It 
then builds a dynamic request using DII 
according to the signature of the service 
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with which it is associated, in this case 
the get/tems service, and the values of 
the input arguments. The proxy bean then 
invokes the DII request, resulting in an 
interaction between the proxy and the 


ai 


ee . 
ee ee eee ee 


ations. 
— 





1989 - 1999 







Network 







Features, 


lelixaalsiiiaieis| 







Features, 


License 






Manager, 









Year 2000 
Guarantee, 
Best Service 


with every 


WIBU-BOX. 


GRIFFIN 


















France, Hungary, 


Portugal, Syria, USA. WWwWw.Wwibu.com 


















CORBA server, in this case the Invento- 
ry Server. This interaction may occur over 
either an intranet or the Internet via IIOP. 
When the request completes, the proxy 
bean extracts the output arguments and 
results of the request and caches them 
in a form that may be easily accessed 
via its JavaBean-compliant interface. The 
proxy bean then generates a new Java- 
Bean event and publishes this event to 
all its registered listeners to notify them 
that the request is complete. These lis- 
teners may then get the results of the re- 
quest from the proxy through its Java- 
Bean interface. Note that all interactions 
between the proxy and servers are di- 
rect using IIOP, rather than via the web 
server. This approach leads to an archi- 
tecture that is efficient, will successfully 
scale without the formation of a bottle- 
neck at the web server, and is not “web- 
server-centric.” 

While the architecture I’ve presented 
here shows how to publish the services 
provided by CORBA servers as web ser- 
vices, the same architectural approach 
may be used to publish any type of serv- 
er developed with a variety of middle- 
ware technologies and protocols. The 
proxy used in the architecture encapsu- 
lates and uses DII to interact with the 
CORBA server with which it was asso- 
ciated. DII is a client-driven interface, 
and interactions between the proxy and 
server are initiated by the proxy. To fa- 
cilitate other communication paradigms 
(for example, true publish and subscribe) 
it is necessary to have server callbacks 
where an interaction between the proxy 
and server is initiated by the server. To 
facilitate this, a similar proxy could be 
developed based on the CORBA Dy- 
namic Skeleton Interface (DSD. 

This architecture offers significant ad- 
vantages. It decouples application devel- 
opment and server development, allowing 
organizations to focus limited, expensive, 
distributed- object systems server devel- 
opment expertise on the development and 
publication of web services. On the oth- 
er hand, more abundant and less expen- 
sive application-development expertise 
may be focused on reusing these web ser- 
vices. Since application developers don’t 
require distributed-object systems exper- 
tise to reuse these web services, training 
may be focused on server developers, 
thereby minimizing training costs and de- 
lays required before a new project starts, 
as well as development costs and delays 
typically associated with a complex new 
technology. 

Furthermore, this architecture also pro- 
vides a layer of abstraction between the ap- 
plication and distributed-object middleware, 
effectively wrapping the middleware im- 
plementation and decoupling applications 
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from it. The advantages of this layer of ab- 
straction are twofold: 


e It allows a particular middleware prod- 
uct to be changed during the lifetime of 
the system without any impact on the 
applications using it. This in turn allows 
companies to rapidly assimilate and lever- 
age the benefits of distributed- object tech- 
nology without having to first go through 
tedious and costly research and evalua- 
tions to make a selection from a vast 
range of middleware products. 

e This layer of abstraction facilitates the 
integration of services provided by a va- 
riety of different types of servers into a 
unified web interface, allowing appli- 


cation developers to reuse these differ- 
ent types of services as web services all 
in the same way. 


Additionally, with the recent mainstream 
growth of distributed-object technology, 
particularly CORBA (for example, JavaIDL 
in JDK1.2), this approach addresses a grow- 
ing need to lower the hurdles associated 
with new organizations and individuals as- 
similating this powerful technology and ac- 
celerating the realization of its benefits. 


Conclusion 

To date, the Web has undergone tremen- 
dous growth and proven itself in a variety 
of information systems. On a separate tier, 





distributed-object systems, and in particu- 
lar CORBA-based systems, have proven 
themselves in mission critical, enterprise, 
distributed- object systems. In this article, 
I’ve presented an architecture that leverages 
the strengths of both web and distributed- 
object systems to create web services that 
deliver the power of distributed- object sys- 
tems and CORBA, yet may be accessed and 
reused with standard web tools and no 
CORBA expertise. This article illustrates one 
approach that paves the way for a new 
breed of sophisticated web services that are 
required to facilitate more powerful, auto- 
mated, business services. 


DDJ 





Listing One 


module StoreServer { 
struct ItemDescription { 
long year; 
string manufacturer; 
string model; 
string description; 
3 
struct ItemRecord { 
ItemDescription description; 
double cost; 
¥3 
typedef sequence<ItemRecord> ItemSequence; 
interface InventoryServer { 
ItemSequence getItems( in long year, 


in boolean includeBefore, 


Listing Two 


// Instantiate proxy bean. 


DynamicRequest request = (DynamicRequest) Beans 
.instantiate( null, "corbabeans.InventoryServer1_getItems" ); 
// Set dynamic request input arguments. 


request.setArgParamVal( "year", 
request.setArgParamVal( "includeBefore", 


new Integer( 1997 ) ); 
new Boolean( false ) ); 


request.setArgParamVal( "includeAfter", new Boolean( false ) ); 


// Invoke dynamic request. 
request.invoke(); 


// Get results from invoking dynamic request. 
int numItems = ( (SequenceParameter) request 
.getReturnParam( "return" ) ).getLength(); 


for( int i=@; 


i < numItems; ++i ) { 


System.out.println( request. getReturnParamVal ( 
"return[" + i+ "].description.manufacturer" ) ); 


in boolean includeAfter ); } 
long inventory( in ItemDescription itemDescription ); 
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ommand-and-control is a user inter- 
face that lets users interact with ap- 
plications by speaking to the com- 
puter, rather than using traditional 
input devices such as the mouse or key- 
board. There are several commercially 
available toolkits that make it possible to 
implement command-and-control voice 
recognition in Win32-based programs, in- 
cluding IBM’s VoiceType and IBM Via- 
Voice (see http://www.software.ibm.com/ 
is/voicetype/dev_home.html), and Drag- 
on Systems DragonXTools (see “Exam- 
ining the Dragon Speech-Recognition 
System,” by Al Williams, DD/, July 1998, 
and http://www.dragonsys.com/). For a 
comprehensive list of companies that 
provide speech-recognition engines and 
related tools, see http://www.tiac.net/ 
users/rwilcox/speech. html. 

In this article, I'll focus on the Microsoft 
Speech (SAPD) SDK. In addition to docu- 
mentation, tools, and sample code, the 
Microsoft Speech SAPI SDK includes code 
that can be freely redistributed with ap- 
plications or speech engines. At this writ- 
ing, the current version of the SDK is 4.0a. 
The SDK itself is freely available at 
http://research.microsoft.com/stg/. In ex- 
amining the Speech SDK, I'll demonstrate 
how you add command-and-control 
voice recognition to applications using 
the Microsoft SDK. The sample code 
(available electronically; see “Resource 
Center,” page 5), includes a program that 
shows how voice control is implement- 
ed and used, plus routines and classes 


Peter is coauthor of Windows Undocu- 
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you can reuse in your own applications. 
The Speech SDK handles both command- 
and-control voice recognition and text-to- 
speech dictation. Command-and- control 
can be used in almost any application 
and has some definite advantages, es- 
pecially with applications where your 
hands need to be busy with something 
other than typing. Text-to-speech, on the 
other hand, can be used for the visual- 
ly handicapped, as well as for verifica- 
tion of command-and-control commands 
without users needing to see the screen. 

This COM-based API is extensive and be- 
yond the scope of this article. For the near 
future, most applications will use command- 
and-control, and only a subset of the com- 
plete API. Still, with this subset, you can 
easily give users an extensive vocabulary to 
work with. 


The Voice-Command Object 

The first thing you need to do to add 
command-and-control voice recogni- 
tion to applications is create a voice-com- 
mand object. Assuming that you have 
voice-recognition software installed, 
all you need to do is call CoCreateln- 
stance( ): 

CoCreateInstance(CLSID_VCmd, NULL, 


CUSCTX LOCAL. SERVER, 
IID_IVoiceCmd,(LPVOID* )&pIVoiceCmd) 


where CLSID_VCmd is the class ID for the 
voice-command object, IID_IVoiceCmd is 
the reference ID for the interface you want, 
and pIVoiceCmd is of type PIVOICECMD 
(defined in Microsoft's SPEECH.H header 
file for the Speech API). pIVoiceCmd 
places the indirect pointer to the voice- 
command object’s voice-command inter- 





Examining Microsoft's 
Speech SDK 


Voice-enabling your applications 


face in the plVoiceCmd pointer. You can 
now access your voice-command object. 


The Voice Notify Sink 
The voice notify sink is a COM object you 
create as part of your application. You 
make this object available to the voice- 
command object; it then lets you know 
when commands are spoken via function 
calls to your voice notify sink object. It 
works in the same manner that callback 
functions serve in the Windows SDK— 
it’s just a litthe more tedious to write. The 
good news is that you can use the tem- 
plate ClVoiceNotifySink class I provide 
here in your own application with little or 
no modification. I’ve reused it for several 
applications with only minor changes. 
You create the voice notify sink much as 
you do any COM object. You have the /Un- 
known interface (Querylnterface( ), Add- 
Ref(), ReleaseRef()) and several additional 
functions — the most important of which is 
CommandkRecognize(_) — that are called pe- 
riodically by the voice-recognition engine. 
The voice-recognition engine calls Com- 
mandkecognize(_) when it has recognized 
a command from your list of commands 
with parameters letting you know the 
specifics. 


Voice-Command Menus 

Voice-command menus are lists of com- 
mands your application is expecting. The 
reason it’s called a “voice-command menu” 
is that the structure is similar to the struc- 
ture of windows menus. This is odd, be- 
cause Microsoft’s own research (see its 
speech SDK documentation) shows that 
users prefer the keyboard or mouse over 
voice when it comes to executing menu 
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(continued from page 86) 

commands. While I suppose there’s 
some value in this menu structure, it makes 
things more tedious in the long run and I 
have yet to find a use for it other than repli- 
cating my window menu structure. 





Example 1: The VCMDCOMMAND 
structure. 
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Because they are tedious to build, 
voice-command menus are the only dif- 
ficult part of the Speech API. Voice-com- 
mand menus are made up of an array of 
VCMDCOMMAND structures. All of your 
VCMDCOMMAND structures need to be 
allocated in the same contiguous block 
of memory. Example 1 defines this struc- 
ture. The fields are: 


e dwSize, the size, in bytes, of the 
VCMDCOMMAND structure (needed 
because the abData field is dynami- 
cally allocated). 

e dwFlags, which sets the only important 
flag for most applications —VCMD- 
CMD_VERIFY. This flag should be set 
for any commands that you want users 
to verify before executing. For exam- 
ple, saying “Format C Drive” deserves 
verification before execution. You'd hate 





Example 2: Prototype of CommandRecognize(). 


00) 330. 


to drop your microphone by accident 
and see a dialog box with “Formatting 
C: Drive” pop up. 

dwID, a nonunique ID number you 
can assign to a command. That it’s not 
unique is actually quite handy. For ex- 
ample, you could assign the same ID 
to “Run Wordpad” and “Start Word- 
pad.” This lets you have synonyms for 
different command words or phrases. 
dwCommand, an offset to the command 
phrase itself; for example, “Open File,” 
relative to the beginning of the VCMD- 
COMMAND data structure. 
dwDescription, an offset to the descrip- 
tion of the action performed by the com- 
mand (used by some applications, but 
I usually leave it the same as the com- 
mand itself). Also relative to the begin- 
ning of VCMDCOMMAND. 
dwCategory, an offset to a category 
(“File,” “Edit,” and so on) in which the 
command belongs. This is where the 
similarity to windows menus comes in. 
The Speech API documentation recom- 
mends 20 or fewer categories for per- 
formance reasons. 

dwAction, an offset to the “Action” data in 
abData. This is essentially user-defined data 
that is passed to the application when- 
ever the command is issued by users. 
You can put in whatever you want here. 
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e dwActionSize, the size of the “Action” 
data in bytes. 

e abData, an atray of bytes where your 
command, description, category, and ac- 
tion data are stored. Command, descrip- 
tion, and category are all null-terminated 
strings (which is why the “Action” is the 
only one that requires a size field). 


The reason voice-command menus are 
difficult is that all of the data in the abDa- 
ta field is DWORD aligned. That means 
that the command, description, category, 
and action are all DWORD aligned. Like- 
wise, the final abData field itself is DWORD 
aligned. Like I said, it’s not difficult because 
i's complicated, it’s just tedious. 

To help ease this, I’ve created the 
DWALIGN macro #define DWALIGN(en) 
((len + 3) & (~3)) that takes a length pa- 
rameter and returns a DWORD, or 32-bit 
aligned length. You can pass in the length 
of each of your strings (command, de- 
scription, and category), as well as the length 
of your action structure. Then add these to 
get the total size of your abData field. 

Once you’ve created your array of 
VCMDCOMMAND structures, you're about 
ready. First, you need to fill in an SDATA 
structure, which consists of two fields: dw- 
Size, the size of your entire list of VCMD- 
COMMAND structures and pData, a point- 
er to the beginning of those structures. 


Creating the Voice-Command Menu 
Before creating your voice-command menu, 
you must fill out two more structures. The 
first is the VCMDNAME structure. This is a 
simple structure that also contains two fields. 
The first field is szApplication, which holds 
the null-terminated application name string. 
The second field is szState, which contains 
the state in which the menu is considered 
active. Essentially, you assign a state to 
menus that are available at different times. 
For example, if you have menus for each 
of several dialogs in your program, you 
would only want the menu associated with 
the currently displayed dialog to be active, 
as commands from the other dialog would 
not be valid. In my sample program, only 
one menu and one dialog are used for it, 
so you assign szState the name “Main.” 
The next structure you need to fill in is 
the LANGUAGE structure, which consists of 
a LanguagelD field and an szDialect field. 
These tell the voice-recognition engine which 
language and dialect you want operating for 
this menu. You can pass a NULL instead of 
a pointer to this structure to the MenuCre- 
ate() function and it will pick the default. In 
my case, I use the LanguagelD of LANG_EN- 
GLISH and the dialect of “US English.” 
Finally, you’re ready to call MenuCreate 
using plVoiceCmd->MenuCreate(&uCmd- 
Name, &language, VCMDMC_CREATE_ 
TEMP, &pIVCmdMenuw);. The third parame- 
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ter is a flag. There are several values that 
determine the lifetime of your menu. 
You can add it to the permanent 
database for your voice-recognition sys- 
tem, in which case your application 
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doesn’t have to rebuild the VCMD- 
COMMAND structures every time it runs. 
Also, most voice-recognition systems 
need some sort of training for new com- 
mands that you add. If you make your 
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commands a permanent part of the database, 
you will not have to retrain it when you re- 
run your application. In this case, I've pro- 
vided a sample program and don’t want to 
waste space in your voice-recognition sys- 
tem’s word database, so my menu exists un- 
til the pVoiceCmd structure it’s associated 
with is released. 

The fourth and final parameter is the 
address of a pointer to an [VCmdMenu 
interface. This is how you now work with 
the voice-command menu. The first thing 
you want to do is deactivate the voice 
menu by calling plVCmdMenu->Deacti- 
vate(). Once this is done, you can add 
your commands by calling p/VCmdMenu- 
->Add(nCommands, sData, NULL), in 
which nCommands is the number of 
commands in the sData structure. The 





third parameter, which I pass as NULL in 
my application, is the address of a 
DWORD. Commands can be added to a 
menu one at a time or in groups. This 
third parameter tells you what the start- 
ing command number was for the group 
that you added. For example, if there are 
33 commands currently in your command 
menu, and you add 15 more, the first of 
those 15 will be command number 34, 
and that is what will be placed in the 
DWORD. 

Finally, you’re ready to activate the 
voice menu using plVCmdMenu->Acti- 
vate(hWnd, NULL). The first parameter 
is the window handle of a window. 
When that window has the focus, this 
voice menu is active. The second pa- 
rameter, which you pass as NULL, tells 
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the engine to only recognize these com- 
mands when the recognition engine is 
awake. The other option, the flag 
VWGFLAG_ASLEEP, tells the engine to 
recognize this command only when the 
recognition engine has been put to sleep. 
Its purpose is to add a command that 
tells your recognition engine to wake up 
and start recognizing commands. 


Back to CommandRecognize() 

The CommandRecognize() function in 
the voice recognize sink gets called each 
time the recognition engine recognizes 
one of your commands. Example 2 is the 
prototype for CommandRecognize( ). 

There are only a few fields in Example 
2 that are really important. The first is the 
dwIlD field, which contains the dwID for 
the command that you assigned. This is 
useful for identifying the command. 
dwFlags tells you if the VCMDCMD_VER- 
IFY flag was assigned to the command. 
dwActionSize and pAction are the size and 
pointer to the Action structure made in 
the VCMDCOMMAND structure. Finally, 
pszCommand is a pointer to the null- 
terminated string with the command that 
was recognized. This may be useful if 
you've assigned a single ID to several 
commands. 

That’s all there is to it. Your program 
can now recognize voice commands 
you've created. As always, you should 
read the SDK documentation to become 
more familiar with the other aspects of 
the SDK. You never know, sometimes 
you find features that you didn’t realize 
you needed. 

The sample program (available elec- 
tronically; see “Resource Center,” page 5) 
is an example of how to use voice recog- 
nition. Figure 1 shows this program run- 
ning. Because this is command-and- 
control, you can’t say someone’s name 
unless you add the name to the voice- 
command menu. Instead, I add the com- 
mand “Name,” which takes you to the 
Name field so that you can type the name. 
For the sex and age fields, you just have 
to say a sex and an age, and those fields 
will be filled in. In this case, I could have 
said “Twenty Nine. Male.” or “Male. Twen- 
ty Nine.” Either way the fields would be 
filled. If you say “Sex” or “Age,” it will 
put the focus in those controls, to allow 
quick typing. Finally, there are three 
checkboxes. To toggle their states, sim- 
ply say, “Disabled,” “Admin,” or “Unlim- 
ited.” As for the age field, I have to ad- 
mit to being lazy. It only accepts ages 
between 18 and 53. I got tired of spelling 
out numbers. 


DDJ 
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Michael Swaine 


his spring, as I was finishing the new 

edition of my computer history book 

Fire in the Valley, | got to thinking 

historically. The year that book was 
originally published, 1984, was historic, 
but not for Orwell’s reasons and not just 
for the release of the Macintosh. Some of 
the events and some of the publications 
of that year are still influencing us today. 
Certain books, in particular, seem worth 
remembering, which may be why they 
still have honored places in my very 
crowded office. My bookshelves contain, 
along with the Redhat Linux Installation 
Manual and Introducing XML, a lot of 
computer history. 


What Was the Point? 

Here, for example, is a book that I keep 
purely for its historic value. The Whole 
Earth Software Catalog 1.0 (WESC), edit- 
ed by Stewart Brand (Doubleday, 1984). 
Obsolete before it was published (A 
book of software reviews? Ridiculous!), 
it still had a large influence in a curious 
way. Agent John Brockman (today he’s 
my agent) secured Brand a huge advance 
for the book, setting a precedent that 
briefly made profitable careers for some 
writers. It wasn’t just WESC: Computer 
books and magazines at the time were 
spinning out of control. In 1984, there 
were 450 different computer magazines, 


Michael is editor-at-large for DDJ. He can 
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some looking like phone books for medi- 
um-sized towns. It was an inflection 
point; soon a shakeout decimated the 
ranks. As a writer, I remember those 
(predecimation) days fondly, even if I 
didn’t get a seven-figure advance, as 
WESC reportedly did. (And Brockman 
isn’t cutting that kind of deal any more, 
just in case you were wondering.) 
WESC was itself heavily influenced by 
the Whole Earth Catalog and its succes- 
sors, also the brainchildren of Stewart 
Brand. My own 1984 work on WESC in- 
troduced me to Brand, and I was grate- 
ful for that. Brand keeps popping up in 
the most interesting places in high-tech 
development. He wrote an article about 
Xerox PARC for Rolling Stone magazine 
ages ago that was the first most of the 
world had ever heard of the place. It was 
Brand who was running the camera dur- 
ing that famous 1968 Joint Computer 
Conference presentation in which Dou- 
glas Engelbart demonstrated most of the 
technology behind the graphical user in- 
terface and the Internet. And, in 1984, 
he was the motive force behind the first 
Hacker’s Conference, a truly legendary 
event. I was there, and I can confirm that 
Steve Wozniak washed dishes. As we sat 
in a circle telling who we were and why 
we were there, Brand’s comment was 
telling: “I’m just here for the contact 
high,” he said. On finishing WESC, he 
wrote to Nicholas Negroponte at MIT 
asking for a job. Negroponte invited him 






to come east to work in something he 
was going to call the “Media Lab.” 
Brand’s Point Foundation was somehow 
behind the People’s Computer Compa- 
ny, or PCC (I’m not sure of the non- prof- 
it corporate links), and if you don’t know 
what that was, maybe you've heard of its 
spin-off publication—Dr. Dobb’s Journal. 
By 1984 DDJ had all but cut its links with 
Brand, hooking up with a commercial 
publisher (M&T Publishing, later acquired 
by Miller Freeman) and hiring an editor- 
in-chief (me), so when I contributed to 
WESC under the byline Dr. Dobb’s Journal, 
it was strangely circular. 


Fool for Tools 

and the Hacker Ethic 

WESC influenced the world in other 
ways. Money from the book deal Brock- 
man negotiated allowed Brand to push 
on into new areas, notably the WELL. 
The Whole Earth ’Lectronic Letter has 
been one of the most successful and 
long-lived online communities ever. It 
led to marriages and other connections, 
including the connection between Lotus 
Development founder Mitch Kapor and 
former Grateful Dead lyricist John Per- 
ry Barlow that resulted in the formation 
of the Electronic Frontier Foundation. 
Even if the EFF was subsequently co- 
opted and became less relevant than it 
might have been, it was badly needed 
in 1984. In 1983, the FBI had launched 
a theoretically commendable but in practice 
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ill-informed campaign to crack down 
on computer crime. Heavy handed and 
mistargeted, the campaign put gun- 
brandishing FBI agents in children’s bed- 
rooms. The EFF stood up to the FBI and, 
more importantly, educated it. 

One of the most influential people on 
the WELL was Howard Rheingold. I met 
Howard in 1983 while he was re- 
searching Tools for Thought (Simon and 
Schuster, 1985) and I was researching 
Fire in the Valley. Rheingold is respon- 
sible for popularizing and, in some cas- 
es, developing quite a number of good 
ideas. His thoughts on virtual commu- 
nities have inspired many a communi- 
ty, and he was one of the early cham- 
pions of Ted Nelson’s visionary project 
Xanadu. 
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Nevertheless, Xanadu is so rich and so 
right that it has influenced people who 
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have never heard of it. In 1984, that was 
almost everybody, but after Rheingold 
described Xanadu in Tools for Thought, 
publications like The Economist were 
soon writing about it. Rheingold is also 
as responsible as anyone for promoting 
the idea that Ada Lovelace was the first 
programmer. Not everyone accepts that 
view; I presented a debunking argument 
here a couple of months ago. But I still 
like the idea, and am not ready to give 
it up entirely. Another book was in the 
works at the same time as Fire in the Val- 
ley and Tools for Thought— well, I sup- 
pose a lot of books were, but I remem- 
ber crossing paths with Rheingold and 
the author of this particular other book 
in the researching of my book. We were 
all interviewing the same people, it 
seemed. 

The other book was Hackers, by 
Steven Levy (Anchor Press/Doubleday, 
1984). Richard Stallman, founder and 
guiding light of the Free Software Foun- 
dation, is so dedicated that he would 
probably be doing just what he’s doing 
today even if he hadn’t been immortal- 
ized in Hackers as the last true hacker, 
but he would be much less well known. 
Levy really nailed the spirit of MIT’s ar- 
tificial intelligence lab in the 1950s and 
60s, and in so doing, communicated the 
hacker ethic to vastly more people than 
would have heard of it otherwise. It’s still 
alive, more vibrant than ever, in the free 
software and open source software move- 
ments, and Levy deserves some of the 
credit for that. Brand recognized right 
away the importance of Levy’s book: The 
aforementioned Hacker’s Conference was 
convened, in part, to celebrate the pub- 
lication of Hackers. 


The Net meme 
and the Little Red Book 
I wonder if any of you remember The 
Netweaver’s Sourcebook (Addison Wesley, 
1984)? If so, I’d be interested to hear from 
you at mswaine@swaine.com. The book 
was published in 1984 and I immediately 
commissioned an article for DD] from its 
author, Dean Gengle. I knew then that 
there was a high idea density in the book, 
but I’m more impressed than ever, look- 
ing back on it with 15 years of perspec- 
tive, to see how much it anticipated. 
Gengle does a credible job of intro- 
ducing null modem cables and ASCII, 
NAPLP, and LAN topologies, but the dis- 
cussion is not deep. This is a broad 
book. The breadth is best suggested by 
running through the topics covered, al- 
though the risk is that it will sound like 
just a list of trendy buzzwords. It is that, 
too, I suppose, but if some of the words 
are trendy now, recall that the book was 
written 15 years ago. The trendy buzzword 
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list: information economy, memes as 
metaphors, holons and hierarchy, noo- 
spherics, softspaces, the infosphere, fil- 
ters, metaprograms, privacy, ethics and 
etiquette, computopia, the culture of the 
entrepreneur, transforming the Bill of 
Rights, the biz biz, politics and telepo- 
lis, new world information order, fami- 
ly networks, distributed network orga- 
nization development, cellular mobility, 
planetary linkage. Some will be turned 
off by the language and judge it too hard 
to find any substance in this book, which 
spends much of its early chapters at an 
ethereal, general systems-like level. Alvin 
Toffler, R. Buckminster Fuller, and 
Richard Dawkins are all cited within a 
few pages of one another in the first 
chapter. The concepts of mode, 
metaphor, and meme are articulated and 
differentiated. “Who cares?” I can hear 
some readers asking. 

But Gengle was sincerely— and I 
think pretty successfully— trying to ar- 
ticulate a difficult vision of net building, 
or net weaving, that goes beyond any 
particular job and examines its implica- 
tions for building and facilitating real 
human community and communication. 
It’s a world-builder’s networking book. 
I’ve always been fond of it, even if I 
haven't ever actually used it for anything. 
And does anyone remember this one, 
published, I think, as a promotional nov- 
elty? Quotations from Chairman Mor- 
row, by George Morrow, (Morrow De- 
sign Press, 1984). I still have it here on 
my shelf, all 60 tiny pages of it. George 
Morrow was one of the more entertain- 
ing computer company presidents of the 
early days, and this take-off on Chair- 
man Mao’s Little Red Book has some 
genuinely insightful bits. 


The only industrial costs software com- 
panies have is the printing of serial 
numbers. 


Ninety percent of the software gets writ- 
ten in 10 percent of the time. The next 
9.5 percent takes 90 percent of the time. 


The last one-half percent never gets done, 
but the software still gets sold. 


A consultant is someone who’s called in 
when someone has painted himself into 
a corner. He’s expected to levitate his 
client out of that corner. 


Short-sightedness is a virtue when it 
comes to choosing a computer system. 
Know what you need now— not two 
years from now. 


I believe in standards. Everyone should 
have one. 


If I quote any more from such a tiny 
book, it will be copyright infringement. 
By the way, I have lost touch with 
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George Morrow. Does anyone know 
where he is? 


Gengle was trying 
to articulate a 
difficult vision of 


net building 


Why 1984 Wasn’t Like 1984 


Books and magazines are convenient 
symptoms of what’s really going on in 


the world or in whatever microworld 
they inhabit. But they don’t tell the 
whole story. So here’s what else was go- 
ing on the microcomputer microworld 
in 1984: 

HP introduced a portable computer 
running UNIX, Apple introduced the 
Macintosh, Compaq followed up its spec- 
tacular first year with four new models 
in 1984, and IBM fell on its face with the 
PCjr. Commodore founder Jack Tramiel 
took over troubled Atari. Osborne Com- 
puter Company threw in the towel. Visi- 
Corp and Software Arts were in a death 
struggle over rights to VisiCalc. The 
Source was trying hard to convince 
Americans that they wanted to logon to 
an information utility, and Compuserve 
charged extra if you wanted to logon to 
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its service with a 1200 baud modem; but, 
by year’s end, 2400 baud models would 
be commonplace. Borland introduced 
the first PIM, called “Sidekick.” Digital 
Research showed off its GEM graphical 
user interface (it was revived just this 
year aS Open-source software). IBM in- 
troduced TopView. And, to the delight 
of us computer history buffs, the Com- 
puter Museum opened in Boston. 

But the big news of 1984 in hardware 
and system software and user experience, 
of course, was the Mac. 


Vibrations, 

Grids, and Ducks 

It is historical fact that the Macintosh, 
pitched with that memorable superbowl 
commercial in January 1984, introduced 
the ubiquitous graphical user interface 
to the world. (A list of disclaimers is nec- 
essary here: Apple didn’t invent the 
UGUI, it didn’t make it ubiquitous, and, 
as Ted Nelson likes to point out, it’s A 
graphical user interface, not THE graph- 
ical user interface.) But a lot of forces 
were impinging on that same idea space 
at that same time. People had been think- 
ing about the ergonomics of human- 
computer interaction for years, and one 
of those people published an influential 
book in 1984. The Elements of Friendly 
Software Design, by Paul Heckel (Warn- 
er Books, 1984), presumably had an in- 
fluence on the Mac user interface, since 
it was written at the encouragement of 
Larry Tesler, manager of user-interface 
design for Mac’s older, duller sister, Lisa. 
Heckel had written a series of articles on 
software design for InfoWorld and Tesler 
urged Heckel to turn them into a book. 
Heckel lined up an agent John Brock- 
man, who else), and set to work turning 
a handful of articles into a book. Al- 
though next month I'll have something 
to say about a good, just-published book 
on software design by someone who has 
more or less created the profession of 
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software designer, Heckel’s 15-year-old 
work has some timeless virtues. 

The principles he lays down are, like 
Dean Gengle’s, often abstract. But he 
provides concrete examples for all his 
ideas, no matter how abstract they are. 
By writing at a high level, he produced 
a book that is still relevant today. The 
fact that the examples are all outdated 
doesn’t make them any less useful. 
“Maintain the user’s interest,” he says, 
and exemplifies this rather vague idea 
with a highly concrete example of re- 
calculation feedback in VisiCalc. He pro- 
vides sufficient detail and context in 
screen shots so that we don’t really have 
to have ever used VisiCalc to see the 
point he’s making, or to see exactly what 
he means by keeping the user’s interest. 
We know he’s talking about movement, 
and that the movement must actually 
matter to the user, and that it must hap- 
pen in a particular time frame. It’s a very 
effective book. While I’m talking about 
the graphical display of information, I 
want to slip in a mention of a book that 
I probably first heard of in 1984, al- 
though it was actually published in 1983: 
Edward R. Tufte’s The Visual Display of 
Quantitative Information (Graphics 
Press). Those who know the book need 
no reminder of its virtues and those who 
don’t need more than I have room for 
here; suffice it to say that Tufte’s beau- 
tiful, philosophical, entertaining, and em- 
inently practical book deserves a place 
on your bookshelf if you ever create 
charts or graphs and if you care about 
how they look and communicate. 


Back in Action 

The publication dates are 1983, 1984, and 
1985 for three related books that stand 
together on my bookshelves. The only 
programming books I seem to have 
saved from that era, these three books 
also document the only computer I still 
have that I was using in 1984— my TRS- 
80 Model 100. The books, just for the 
record, are: The TRS-8O Model 100 
Portable Computer, by David A. Lien 
(Compusoft, 1983), The TRS-80 Model 
100 Computer, by Kenniston W. Lord 
(Reston, 1984), and Inside the Model 100, 
by Carl Oppendahl, (Weber Systems, 
1985). Also worth mention, although I 
regretfully don’t have a copy on my shelf, 
is The Model 100 Book, by DDJ editor- 
in-chief Jon Erickson (Osborne/McGraw- 
Hill, 1984). The Model 100 computer (see 
Figure 1), not just for the record, was 
one of the sweetest machines I have ever 
used. It was portable, remarkably small 
for the time, with full-sized, full-travel 
keys, plus a row of user- programmable 
function keys. It was, in fact, mostly key- 
board. There was an 8-line 80-column 
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display above the keys, but the whole 
thing was almost exactly the dimensions 
of a standard pad of writing paper. (Well, 
a two-inch-thick pad.) It had built-in 
programs for word processing, address 
management, scheduling, and commu- 
nications (it had a built-in modem), and 
a Basic interpreter that supported bit- 
mapped graphics and simple music gen- 
eration. It also proved surprisingly easy 
to code simple Z80 assembly routines 
for the thing to get around the limits of 
interpreted Basic. And the accessible 
ROM socket made it possible to add full- 
featured word processors and spread- 
sheet programs. 

As a writer, I fell in love with it, and 
took it to conferences where I used it to 
take notes, annoying people with my 


Still reinventing? 





clicking. It was more portable and even, 
in some sense, friendlier than any com- 
puter that I’ve used since. I recently put 
the Model 100 back in action as my work- 
shop computer. In addition to my writing, 
I now seem to have acquired certain du- 
ties involved with my partner Nancy’s new 
farm, and the Model 100, with its built-in 
schedule and word-processing programs 
and Basic interpreter, will serve very nice- 
ly for maintaining my workshop to-do list, 
scheduling equipment maintenance, and 
performing simple calculations. It’s nice 
to have it back. 
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Herb and Me 





Al Stevens 


n April of this year, I participated in a 
panel discussion for the Java/C++ Spe- 
cial Interest Group of the Technical Uni- 
versity of Silicon Valley (formerly the 
San Francisco Bay Area Center for Ad- 
vanced Technology). The discussion was 
held at the offices of Mentor Graphics in 
San Jose, California. The featured speak- 
er was Herb Schildt, author of numerous 
computer books, and this event was the 
first stop of the “Herb Schildt World Tour,” 
or so the T-shirts proclaimed. I was invit- 
ed as a featured guest panelist because I 
am also a book author, write this column, 
and have a long-standing friendship with 
Herb. What better draw than to have two 
internationally famous computer lumi- 
naries on stage at the same time? I agreed 
to do it because the deal included an all- 
expense-paid two-day trip to San Jose and 
a free Herb Schildt T-shirt. ’m not sure 
which perquisite was more compelling. 
Dr. Dobb’s Journal generously covered 
my expenses for the trip. In line with the 
magazine’s liberal travel policies as es- 
tablished by editor-in-chief Jon Erickson, 
I flew economy class (“steerage” would 
be a better description) on the Grace L. 
Ferguson Airline and Storm Door Com- 
pany, otherwise known as GLF. I had the 
usual accommodations at Jim’s No-Tell 
Motel (“$3 for 3 hours, $5 a night”) near 
the airport, conveniently located just un- 
der the departure corridor for runway 27, 
and was afforded unlimited use of the 
company car— an orange and black 1972 
Plymouth Fury, which was formerly a San 
Jose taxicab and which DDJ maintains for 
visiting contributing editors. By “maintains” 
I don’t mean to imply actual maintenance. 
Jon doesn’t fix it. He just keeps it in the 
parking lot of an abandoned strip mall 
next to Jim’s and leaves the keys in the 
ignition. The neighborhood notwith- 
standing, theft has not been a concern. 


Al is a DDJ contributing editor. He can be 
contacted at astevens@ddj.com. 
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I was told that Herb’s publisher, Osborne 
Books, was giving Herb the same kind of 
red carpet treatment that I receive. Pub- 
lishers like Osborne and DDJ recognize the 
value of their authors and spare no ex- 
pense keeping us happy and content. 

On the evening of the panel discussion, 
I got a jumpstart from a fellow patron of 
Jim’s and coaxed the Plymouth, lurching, 
belching, and smoking, the few miles to 
the headquarters of Mentor Graphics. As I 
approached the circular driveway in front 
of the main entrance to the reception area, 
I saw a crowd of spectators being held at 
bay behind ropes by uniformed guards. An 
assemblage of eager photographers and 
reporters stood nearby, cameras and mi- 
crophones poised and at the ready. A video 
camera was in place to capture the event 
for the evening news. Obviously, they were 
all waiting for a first glimpse of the 
renowned guest speakers— me and Herb. 

Just as I was about to turn into the 
driveway, a shiny new black stretch limou- 
sine cut me off and slid quietly ahead. It 
glided to a stop in front of the curb by 
the entrance. The crowd pushed forward 
in anticipation. Hoping the Plymouth’s 
brakes would hold, I stopped behind the 
limo and waited and watched. 

One of the guards stepped briskly to the 
rear passenger door of the limo and opened 
it. A hush fell over the crowd. After what 
seemed an eternity, a leg clad in designer 
jeans emerged from the limo, and a de- 
signer sneaker hit the pavement with an 
authoritative thud. The crowd oohed and 
aahed. Cameras began to flash furiously. 
The video camera started grinding away. 
Then it happened. What everyone was 
waiting for. A beaming Herb Schildt pulled 
his imposing figure from the limousine and 
stood on the sidewalk waving to his ad- 
mirers who were now screaming, “Herb! 
Herb! Herb!” A young girl fainted. Reporters 
with microphones pushed forward and be- 
gan firing questions at Herb. He smiled and 
waved them off, going instead to the edge 





of the crowd of spectators who pushed au- 
tograph books and copies of his bestseller 
Teach Yourself Minesweeper at him to sign. 
Herb graciously took the time and auto- 
graphed every one before disappearing 
into the lobby followed by an entourage of 
aides and assistants who appeared from 
nowhere to tend his every need. 

The limo pulled away and into the VIP 
parking area. I lurched the Plymouth for- 
ward and came to a screeching stop. I 
looked around for the fans and reporters, 
but the sidewalk was empty. They had all 
disappeared into the building, each hop- 
ing to get another glimpse of Herb, to 
overhear some tidbit of Herb’s conversa- 
tion with his staff, perhaps to get a shred 
of his clothing, a lock of his hair. 

A uniformed guard came around to the 
driver’s side of my vehicle and sternly sig- 
naled for me to lower the window. The 
windows don’t work in the Plymouth, so 
I opened the door. The guard jumped 
back lest the rusty, pockmarked door 
touch his crisp new uniform. 

“What do you want?” he barked. 

“I’m Al Stevens,” I said importantly, wait- 
ing for the spark of recognition that did 
not come. “I’m speaking here on the pan- 
el tonight.” 

“Oh, yeah? Well, park that heap around 
back outta sight in the delivery area,” he 
ordered. As I meekly pulled the door shut, 
he added, “And wouldya come in through 
the kitchen, please. The guests are start- 
ing to show up.” 


The Panel 

About 50 people attended the panel dis- 
cussion. Our moderator was Marian Cor- 
coran of the Technical University of Silicon 
Valley Chttp://www.centeradv.com/), and 
many of the attendees were students of the 
classes she teaches on Java and Internet 
programming. Mentor Graphics provided a 
large room with folding chairs set up for 
the audience and a table and PA system for 
the panel. DDJ’s Philippe Lourier captured 
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the evening, which you can view in its en- 
tirety at http://www.ddj.com/technetcast/. 

Herb and I were the only panelists. Herb 
set the tone of the discussion with his 
Opening remarks about “where program- 
ming is today, how we got there, and 
where we are going.” He observed that 
despite attempts over the years to raise 
levels of abstraction with advanced lan- 
guages and programming tools, program- 
ming seems to be getting harder rather 
than easier. This opinion evoked much re- 
action and response from the audience, 
who mostly agreed with Herb’s assertion. 
We spent the evening discussing levels of 
abstraction, the increased demand for more 
complex applications, performance and 
ease-of-use issues that distinguish C++ and 
Java, future programming paradigms, the 
process of language standardization, the 
problems facing organizations that want 
to upgrade their applications to Standard 
C++, and many other such topics. 

Herb asked the C++ programmers in 
the audience how many were aware that 
Standard C++ specifies header files that 
are different from traditional C++ and 
that using those files and the Standard 
C++ Library has implications. No one in 
the audience knew about that. Further 
discussion revealed that none of them 
are actively looking at or concerned with 
the issues of Standard C++ as they ap- 
ply to the software development projects 
with which the programmers are cur- 
rently involved. Their interest was raised, 
however, when we on the panel dis- 
cussed some of those implications, and 
they began asking questions about the 
implications of changing to a conforming 
compiler. 

This pseudopoll that our panel con- 
ducted among this small sample of Sili- 
con Valley programmers raised some in- 
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teresting questions. E-mail from readers 
of this column indicates to me that DD/ 
readers are very much aware of these is- 
sues, partly because we discuss them here 
and partly because typical DD/ readers 
tend, I think, to be interested in issues that 
might someday affect them. My partici- 
pation on Usenet groups discussing C++ 
has also involved contact with corre- 
spondents who know a lot about these 
things. Which group is more typical of the 
industry? Herb’s feeling is that our audi- 
ence that evening was typical, that 90 per- 
cent of C++ programmers are blithely un- 
aware of what’s coming, and that those 
who communicate publicly about such is- 
sues naturally tend to comprise the 10 per- 
cent who are aware. of and concerned 
about them. 

Although much of the panel’s discussion 
with the audience was about Java, I will 
bypass those discussions here because I 
am not well qualified to comment on them. 
Herb has written Java books, and Marian 
teaches Java. The Java-related opinions of 
people who know Java well carry more 
weight than mine (except when someone 
suggests that Java is better than C++, of 
course). You may observe the panel on 
TechNetcast.com and draw your own con- 
clusions about the Java discussions. My sole 
contribution to that particular topic was to 
point out the futility of comparing the mer- 
its of the two languages in order to declare 
one of them the superior language. C++ 
and Java serve different target operating 
environments. What each does best the oth- 
er does poorly. I'll stick to the C++ parts 
of the panel discussion and expand on 
some subjects that we did not have time 
to explore in detail. 

As we got into the issue of porting a 
legacy C++ application to Standard C++, 
Herb and I pointed out, as an example, 


that the cout object in the global name- 
space as defined in <iostream.h> is a dif- 
ferent object than the new std::cout ob- 
ject as defined in <iostream>. They both 
have almost identical behavior, in that they 
write data strings to the standard output 
device, but they are different objects be- 
cause they are objects of classes that are 
implemented differently. Depending on 
how the compiler implements both li- 
braries, the traditional and the standard, 
a program might be able to use both head- 
ers and both objects. That could happen 
if you compiled a new source file with 
standard conventions and linked it with 
an old object file that was compiled with 
traditional conventions. That’s not a good 
idea, however. The Standard makes no 
mention of the old-style headers and the 
existence of old-style libraries. There is, 
therefore, no formally sanctioned, uni- 
versally accepted, standard definition of 
old-style stuff. It just is what it is. 

The problem is further complicated if 
you try to pass an object of type sid.-if- 
stream, for example, to a function that ex- 
pects an object of type ifstream. The com- 
piler rejects the function call because the 
types do not match unless the imple- 
mentor has kindly included a conversion 
constructor or conversion member func- 
tion, which is unlikely and certainly not 
required by the Standard. 

One might ask why the committee put 
everything in the std namespace. The 
anomalies I just mentioned should help 
to answer that question. Acknowledging 
that compiler builders must continue to 
support traditional, noncompliant libraries 
for the sake of legacy code, the commit- 
tee needed a way to insulate the similar- 
ly named classes, functions, and objects. 
That reason also explains why the com- 
mittee chose a different header naming 
convention. 

Another reason is that, according to 
namespace proponents, few things in a 
perfect program are in the global names- 
pace. Certainly, nothing that the compil- 
er system imposes on the programmer 
other than main should be in the global 
namespace. Having introduced a name- 
space feature to support this concept, the 
committee has to use it. How credible 
would a feature be if its own creators 
avoided it? 

One might ask why the committee did 
not use different names for the new class- 
es, functions, and objects. I can only guess 
at the answer with conjecture as to why 
I would have made that same decision. 
As Herb pointed out to the audience, in 
many cases, a programmer can take an old 
program, qualify all the names with the 
std namespace (or use the dreaded and 
despised std; declaration), change the names 
of the header files to the new .h-less 
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(continued from page 102) 
convention, and recompile. Assuming a 
properly conforming implementation, the 
program will usually work. This is not to 
suggest that you shouldn’t run exhaustive 
tests. You should. But the upgrade is eas- 
ier and less error-prone than it would be 
if all the names and the interface were 
changed. 

It won't be that simple with systems of 
substantial complexity. There is a lot that 
can go wrong, particularly when a soft- 
ware system depends on legacy libraries 
that are trusted but not current themselves. 
Often, the size and complexity of such li- 
braries discourage the programmers from 
wading in and making broad changes just 
to accommodate the upgrade. Other times, 
the source code is not available. My ad- 
vice is to hang on to the versions of com- 
pilers that you used to build working re- 
leased applications. Make the transition 
slowly and conservatively. Keep in mind 
that Standard C++ introduces other small 
changes in language behavior that can 
break your code. 

One might ask why the committee did 
not simply codify existing traditional li- 
braries. The first answer is that those old 
libraries were developed in the absence of 
a Standard and don’t all work alike from 
implementation to implementation. I 


learned that when I was writing C++ ex- 
ercises for my Teach Yourself C++ book 
(mine, not Herb’s). Formatted ostream 
output worked differently between com- 
pilers. The very old C++ conventions 
sprang from early AT&T implementations 
of iostreams, which evolved and changed 
over time. Not all compilers maintained 
consistency with AT&T’s changing con- 
ventions. The second answer is that tra- 
ditional iostreams do not support a wide- 
character format and are unsuitable for 
international data representation. The 
ISO half of ANSI/ISO would not have 
stood for it. 


Unintentional Chairperson 

The panel discussion was a huge suc- 
cess, and we all had a great time. When 
Marian brought the session to a close, 
Herb’s admirers crowded around him for 
some one-on-one. Mostly ignored, I 
hung back with some of his entourage 
and chatted about the Bay Area weath- 
er, which was rotten that day. A young 
man in a black suit (the only suit and 
tie in the room) wheeled in a dolly with 
a load of books and a cash register for 
the official Herb Schildt book sale and 
signing session. I asked the Osborne 
people if the guy in the suit was the limo 
driver; he certainly looked the part. Cer- 


tainly not, they told me, he is the pub- 
lisher. Oops. 

I stayed until all the books were sold 
and signed and all the fans and reporters 
had left. Herb and I said our farewells, 
and he and the driver, er, publisher grand- 
ly led the entourage out to the limo for 
the champagne celebration ride back to 
Berkeley. I thought about the Plymouth 
and wondered where I could get anoth- 
er jumpstart that time of night. I took one 
last look around at the abandoned meet- 
ing room and started out toward the rear 
parking lot where the Plymouth waited in 
exile. The uniformed guard stopped me 
at the door. 

“Where do you think you’re goin’?” he 
demanded to know. 

“Back to the motel,” I answered sheep- 
ishly. “I’ve got an early flight. GLF doesn’t 
fly at night.” 

“Oh no you don't,” he snapped. “You're 
not goin’ anywhere. Somebody’s gotta fold 
up all these chairs and put ’em away.” 
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How Can I Test Java Classes? 


Krishnan Rangarajan 


nit testing is an important element 

of testing software. In object-oriented 

software development, this term 

commonly refers to testing individ- 
ual classes. The term “integration testing” 
denotes testing a group of classes, while 
the term “system testing” refers to testing 
the application as a whole. In the simplest 
and most widely followed testing practice, 
developers of classes are expected to per- 
form unit and integration testing of their 
respective classes before releasing their li- 
brary to other groups. The test team is re- 
sponsible for system testing before re- 
leasing the application to clients. 

There is on-going research in the area 
of testing object-oriented software, and 
a lot more needs to be done. Because 
class testing is the starting point of test- 
ing object-oriented software, under- 
standing the issues involved and devis- 
ing a way to perform effective class 
testing is a crucial first step in delivering 
high quality software. At Man Machine 
Systems, we have developed a new mod- 
el for testing Java classes, called “inva- 
sive testing.” We believe this model can 
make class testing more interesting and 
effective. Testing is typically character- 
ized as a destructive process, so the term 
effectively suggests that the tester must 
be able to uncover a ‘maximum number 
of bugs with minimal effort. (The term 
“tester” as used here denotes a role rather 
than an individual. This means that a de- 
veloper could be a tester.) In this article, 
I'll describe the invasive testing model 
and compare it with conventional unit- 
testing techniques. 


Invasive and 
Intrusive Testing of a Class 
Invasive testing is a technique that uses 
the normally inaccessible elements of a 
class to increase the effectiveness of test- 
ing. When the class under test is modified 
to support testing, it is called “intrusive 
testing.” 

If a class C comprises a set M of meth- 
ods that belong in the class interface, in- 


Krishnan is president of Man Machine 
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mms@giasmdO1 vsnl.net.in or http://www 
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trusive testing typically assumes the exis- 
tence of N additional methods and mod- 
ifications to some or all of the M methods 
to aid testing. The additional N methods 
are not intended to be used by normal 
clients of the class (and are not part of the 
published class interface), but are defined 
purely to support testing. If methods in 
sets M or N access private members of the 
class, then the technique is invasive as 
well. Plain invasive testing does not mod- 
ify the class under test, but would use pri- 
vate details of the class that normal users 
cannot access. 


Conventional Class Testing Strategies 
There are a number of conventional class 
testing strategies, including those that are 
noninvasive/nonintrusive, noninvasive/in- 
trusive, and invasive/intrusive. Table 1 
compares the different techniques I dis- 
cuss here. 

The noninvasive/nonintrusive tester-as- 
client is the most common strategy for test- 
ing classes. Here, the tester writes a driv- 
er in the same language as the class under 
test, and exercises the published methods 
of the class, following a set of test crite- 
ria, such as coverage. Since the driver code 
resides in a different class than the tested 
one, accessibility rules defined in the lan- 
guage apply. Consider the stack imple- 
mentation MyStack in Listing One as an 
example of a Java class to be tested. The 
test driver in Listing Two tests the stack 
class. Assume the existence of test sup- 
port routines such as Test.error(String). 
The test driver is written to test invoca- 
tions of MyStack’s public methods in some 
combination. 

One benefit of this technique is that it 
is intuitive, because it simulates actual us- 
age of the class under test. Also, the class 
tested is the class actually released to the 
customer because no modification is per- 
formed to the class for testing purposes. 

This approach does have its limitations, 
however. Since the tester has to exercise 
public methods in the class interface, cer- 
tain methods can only be tested in com- 
binations, not individually. For example, 
the push (or pop) method cannot be test- 
ed in isolation. As a result, if the push/pop 
combination fails, it could be due to a bug 
in either or both the methods, and addi- 





tional tests may be needed before the ac- 
tual bug may be isolated. Even if the 
push/pop combination matches, there is 
no guarantee that they are both correct; 
it is conceivable that both have bugs that 
coincidentally produce the correct be- 
havior. Once again, additional combina- 
tions will have to be tried. Also, it is not 
always possible to exercise all parts of the 
implementation adequately by invoking 
public methods alone. Finally, there is no 
way to test interfaces. 

In the noninvasive/intrusive tester-as- 
client scenario, the class to be tested is 
modified to support testing. Accessible 
getter and setter methods are added for 
all state variables that are otherwise in- 
accessible. Alternatively, all elements of 
the class are made public to grant unre- 
stricted access. This permits the tester to 
overcome the limitations of the nonin- 
vasive/nonintrusive approach. The My- 
Stack class in Listing One, according to 
this strategy, might be modified as in List- 
ing Three. 

The test driver is now rewritten to take 
advantage of private details of the class 
to perform more effective testing. Listing 
Four shows how this can be done. 

One benefit of this approach is that the 
semantics of individual methods can be ver- 
ified. This can reduce the test effort, be- 
cause the number of methods is much less 
than the number of method combinations. 

The limitations of the technique, howev- 
er, are that the class tested is different than 
the one released to a client, and that the 
tester needs to understand the class imple- 
mentation details, in addition to its interface. 
For complex classes, this could be quite dif- 
ficult. Also, if the class implementation 
changes in the future, the driver code will 
have to be appropriately modified. Finally, 
the source code for the class is required. 

An invasive/intrusive technique, which 
is to automatically instrument the code 
with assertions, is a promising approach 
for testing object-oriented software. In this 
case, the developer embeds assertions 
(class invariant, method preconditions, and 
method postconditions) inside comments 
in the source code. A preprocessor pars- 
es these assertions and emits the modi- 
fied source where the assertions have been 
appropriately moved to method bodies. 
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Table 1: Comparing testing techniques. 


The preprocessed code is compiled using 
a standard Java compiler. The resulting ap- 
plication is then run as if it were the origi- 
nal program. Any violation of contracts will 
be reported by the assertions layer. Listing 
Five is an example of how assertions might 
be specified. 

The assertion language depends on the 
tool used; currently there is no standard. 
The previous example uses a syntax sup- 
ported by our tool, JMSAssert, which gen- 
erates a JMScript test script file. Reto Kramer's 
iContract (http://www.reliable-systems 
.com/) is a tool in the public domain that 
supports assertions in Java classes. 

One benefit of this invasive/intrusive 
technique is that reasonably complex class 
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invariants, as well as preconditions and 
postconditions, may be specified. Since 
the assertions are defined as part of 
class/method comments, the source can 
be recompiled to get uninstrumented class- 
es. Finally, this approach assists in testing 
the complete application. 

However, one of its limitations is that 
the class tested is different than the one 
released to a client. Also, source code has 
to be available to instrument with asser- 
tions. Furthermore, in many cases, the as- 
sertion language is proprietary, so mov- 
ing to another preprocessing tool is 
difficult and to test classes individually 
(not as a sealed-off application), a test 
driver still has to be written. Finally, indi- 
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vidual methods cannot be tested because 
of access restrictions. 

Another invasive/intrusive approach is 
when the tester is the developer. In this 
case, the test driver resides within the class 
being tested; see Listing Six. Typically, this 
is the main method or a test method that is 
static. When it is invoked, the test logic is 
exercised. Because the method is part of 
the class, access restrictions do not apply; 
all elements of the class can be accessed. 

One of the benefits of this invasive/in- 
trusive approach is that there is no need to 
convert private elements to public for the 
sake of testing. Also, the test driver for the 
class is self-contained, so the driver is more 
likely to be in syne with the class. 

Its limitations are that the test driver can- 
not be reused when the class evolves. For 
each version of the class, a correspond- 
ing version of the driver inside the class 
(perhaps copying and pasting from a pre- 
vious version) must be developed. To fa- 
cilitate regression testing, it is better to 
have the driver separated from the class. 
Again, the source code must be available, 
and when the class is delivered to a client, 
the test driver constitutes excess baggage. 
However, if the driver is removed from 
the code, then two versions of the class 
have to be maintained, one with the driv- 
er and another without the driver. 


Invasive Testing 
It is a widely acknowledged fact that test- 
ing object-oriented software is more dif- 
ficult than testing nonobject-oriented soft- 
ware. In “Design-for-Testability For 
Object-Oriented Software” (Object Maga- 
zine, July 1997), Jeffery E.Payne, Roger 
T.Alexander, and Charles D.Hutchinson, 
point out that “from the value of testing per- 
spective, information hiding reduces the abil- 
ity for faults to propagate to an observable 
output and hence reduces the likelihood 
that faults will be revealed during testing.” 
The invasive model lets the tester tun- 
nel through the information-hiding barri- 
er and write a driver that accesses the nor- 
mally inaccessible elements of a class. This 
can occur without making changes to the 
class source. In fact, the approach does 
not require Java source code to be avail- 
able for testing purposes. To assist in 
achieving this, we’ve developed a script- 
ing language called “JMScript” that is lay- 
ered on Java. The language lets testers 
write a script that instantiates Java objects 
and send messages to them. This is simi- 
lar to what happens in Java itself. Like 
many other scripting languages, JMScript 
is weakly and dynamically typed. These 
types are associated with values of objects 
and not with variables. Once a Java ob- 
ject is instantiated in the script, any ele- 
ment of the object, be it private or pro- 
tected, can be accessed without restriction. 
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The JMScript driver (available electron- 
ically; see “Resource Center,” page 5) il- 
lustrates one way of testing the MyStack 
class. The script can be executed by run- 
ning the command-line version of the in- 
terpreter (or the more sophisticated JVer- 
ify environment can be used, that includes 
the interpreter and much more). 

The script accesses even the private el- 
ements of a class, bypassing Java’s access 
control mechanism. Notice how assertions 
are used after every method call to check 
the postcondition. However, explicitly 
checking the postconditions can litter the 
script with too many assertions. There is 
a more convenient way to do this, as in 
the test script in MyStackTest2.jms (avail- 
able electronically), which illustrates that 
a tester can identify an invariant for a class, 
a set of preconditions and postconditions 
for methods and register those with the 
interpreter. When a method is invoked 
from the test script, the corresponding pre- 
condition, postcondition, and invariant 
routines are automatically and appropri- 
ately executed by the interpreter. The se- 
quence followed by the interpreter is: 


e Check class invariant. 

e Check precondition for the method. 
e Invoke method. 

e Check postcondition for the method. 
e Check class invariant. 


There are exceptions to this rule, but 
that is beyond the scope of this article. 

It is possible to do better than setting 
up triggers manually. If the class source 
is available and assertions are embedded 
in comments as in Listing Five, another 
utility called “JMSAssert” will parse these 
and automatically generate a script file 
containing appropriate triggers. 


Testing State Machines 

The invasive model provides a convenient 
approach to testing state machines. In gen- 
eral, testing a state machine tends to be 
fairly involved because of the potentially 
infinite number of states possible. The 
ability to access private details could con- 


siderably reduce the effort (the downside 
is that intimate knowledge of the class 
may be required). 

Consider the state machine in Figure 1. 
(The Java source code for the state ma- 
chine is available electronically. For clar- 
ity, I’ve left out several optimizations.) 
How can you prove that the Java state- 
machine program accepts all the strings 
as per the state-machine specification of 
Figure 1? Clearly, testing with all strings 
is impossible. Fsmtest.jms (available elec- 
tronically) shows how the state machine 
can be tested using JMScript. The basis 
for the testing strategy just used is to drive 
the state machine to each intermediate 
state not allowed normally, and then to 
ensure that when an input is received, it 
transitions correctly to the next state. 

Invasive testing’s benefits include the 
fact that the class under test is not modi- 
fied to support testing. The class tested is 
the same as the class released to a client. 
The source code for the class does not 
need to be available. (This means it is pos- 
sible to test third-party libraries.) The test 
driver accesses implementation details, if 
necessary, to test individual methods, not 
combinations. This can minimize testing 
effort. Class invariant, method precondi- 
tions and postconditions can be complex 
in real situations. The support for such ar- 
bitrarily complex conditions is taken care 
of by providing procedures in JMScript. 
Because the test driver is separate from 
the class being tested, reuse of the test 
cases is possible throughout regression 
testing. 

A limitation is that the test script is writ- 
ten in a language different than Java. This 
means learning a new language. This ap- 
proach is ideally suited to perform unit test- 
ing of individual classes and integration 
testing of small groups of classes, but not 
for system testing. This relies heavily on 
the commitment of the development envi- 
ronment to the use of “Design by Contract.” 


JVerify Test Environment 
To create, execute, and test JMScript 
scripts, we developed JVerify, a GUI- 


















































































































































































































































































































































































































































































































































Figure 1: Example state machine. 


based Windows application. The envi- 
ronment supports a debugger that allows 
setting breakpoints, and examining the 
execution snapshot through an object 
browser and call stack. Another salient 
feature of the environment is the facili- 
ty to understand a class’s interface from 
its .class file. This can be useful when 
the source for the class under test is not 
available. 


Conclusion 

Testing object-oriented software is more 
difficult because of information hiding. 
Invasive testing makes a tester all pow- 
erful by allowing access to private de- 
tails of the class under test. This model 
renders a class more amenable to test- 
ing (even if it has not been designed for 
testability). This model is also particu- 
larly useful for testing state machines. 
JMScript, layered on Java, has been de- 
signed to support class invasion in the 
context of Java programs. More infor- 
mation about the language and associ- 
ated tools is available at http://www 
-mmsindia.com/. 
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Listing One 


class MyStack { 
private Object[] elems; 
private int top, max; 
public MyStack(int sz) { 
max = SZ; 
elems = new Object[sz]; 
} 
public void push(Object obj) throws Exception { 
if( top < max ) 
elems[topt+] = obj; 
else throw new Exception("Stack overflow") ; 
} 
public Object pop() throws Exception { 
if( top > @ ) 
return elems[--top]; 
throw new Exception("Stack underflow") ; 
} 
public boolean isFull() { 
return top == max; 
} 
public boolean isEmpty() { 
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return top == @; 
} 
} 
Listing Two 


class StackTester { 


public static void main(String[] args) { 
MyStack si = new MyStack (10); // Max of 10 elements 


if( !si.isEmpty() ) 


Test.error("Stack is not empty initially!"); 
StackTester obji = new StackTester(); // An object to stack 


s1.push(obj1); 
if( s1.isEmpty() ) 


Test.error("Stack is empty after a push!"); 


StackTester obj2 = 
if( obj1i != obj2 ) 


(StackTester) si.pop(); 


Test.error("Problem in push()/pop()!"); // ----- (A) 
// ... Other code 


(continued on page 110) 
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(continued from page 109) 
Listing Three 


class MyStack { 
// Private elements are public - FOR TESTING ONLY 
public Object[] elems; 
// Private elements are public - FOR TESTING ONLY 
public int top, max; 
public MyStack(int sz) { 
max = Sz; 
elems = new Object([sz]; 
} 
public void push(Object obj) throws Exception { 
if( top < max ) 
elems[topt+] = obj; 
else throw new Exception("Stack overflow") ; 


} 
public Object pop() throws Exception { 
if( top > @ ) 
return elems[--top]; 
throw new Exception("Stack underflow") ; 
} 
public boolean isFull() f 
return top == max; 
} 
public boolean isEmpty() { 
return top == @; 
} 


Listing Four 


class StackTester { 
public static void main(String[] args) { 

MyStack si = new MyStack (10); // Max of 10 elements 
if( !s1.isEmpty() ) 
Test.error( "Stack is not empty initially!"); 
StackTester obji = new StackTester(); // An object to stack 
si.push(obj1); 
Test.assert((s1.top == 1) && (s1.elems[s1.top-1] == obj1),"Push failed!"); 
StackTester obj2 = (StackTester) si.pop(); 
Test.assert( (si.top == 0) && (obj2 == obj1), "Pop failed!"); 
// ... Other code 
} 


Listing Five 


/** @inv (top >= @) && (top < max) */ 
class MyStack { 
private Object[] elems; 
private int top, max; 
/** @post (max == sz) && (top == @) */ 
public MyStack(int sz) { 
max = SZ; 
elems = new Object[sz]; 
} 
/** @pre top < max; 
a @post (top == topSprev + 1) && (elems[top-1] == obj) 
public void push(Object obj) throws Exception { 
if( top < max ) 
elems[topt+] = obj; 
else throw new Exception("Stack overflow") ; 
} 
/** <assertions here> */ 
public Object pop() throws Exception { 
if( top > @ ) 
return elems[--top] ; 
throw new Exception("Stack underflow") ; 
} 
public boolean isFull() { 
return top == max; 
} 
public boolean isEmpty() (¢ 
return top == @; 


e e e 
Listing Six 
class MyStack { 
ii . Insert stack related elements here. 
// This is the stack test driver. It is part of the class itself. 
public static void main(String[] args) { 
MyStack si = new MyStack (10); // Max of 10 elements 
if( !sl.isEmpty() ) 
Test.error( "Stack is not empty initially!"); 
MyStack obj1 = new MyStack (); // An object to stack 
si.push(obj1); 
Test.assert( (si.top == 1) && (si.elems[s1.top-1] == obj1), 
"Push failed!"); 
MyStack obj2 = (MyStack) sl.pop(); 
Test.assert( (si.top == 0) && (obj2 == obj1), "Pop failed!"); 
// ... Other code 
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Space-Filling Curves 


in Geospatial 
Applications 


Ron Gutman 







magine a database table of homes for 

sale. To find homes in the $140,000 to 

$150,000 price range, you could use the 

SQL query in Example 1(a). Such one- 
dimensional queries are efficiently han- 
dled by the B-tree indexes provided by 
most DBMS systems. However, a B-tree 
index is less efficient for retrieving all 
homes in a geographical area, as in Ex- 
ample 1(b). Using a B-tree index on lon- 
gitude, the DBMS would retrieve all homes 
with a longitude in the desired range of 
longitudes, then eliminate those with a lat- 
itude outside the desired range of latitudes 
(Figure 1). In the process, the DBMS 
would retrieve far more data than required 
before obtaining the final result. Indexing 
on latitude would not help. 

Ideally, the DBMS engine would pro- 
vide a different type of index designed 
for efficient retrieval of multidimension- 
al data. Informix, for example, offers R- 
tree indexes (see “R-trees: A Dynamic 
Index Structure for Spatial Searching,” 
by A. Guttman, Proceedings of the SIG- 
MOD Conference, June 1984). R-trees of- 
fer superior performance and flexibility, 
but adding a new type of index to a 
DBMS engine is not easy. Oracle’s Spa- 
tial Cartridge (http://ntsolutions.oracle 
.com/products/sdo/html/sdo_twp.htm) 
relies on a different approach, one that 


Ron is a senior software engineer for In- 


formix. He can be contacted at guiman@ 
informix.com. 
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can be implemented without modifying 
the DBMS engine. 

Like Oracle’s approach, the technique 
I examine here works in conjunction with 
a B-tree or any other one-dimensional in- 
dex. It relies on the properties of space- 
filling curves to achieve good performance 
and can be implemented by the applica- 
tion developer, because no modification 
to the DBMS is required. 


Spatial Orderings 

A space-filling curve can help index points 
on a map by placing the many points of 
the map’s region into some suitable order, 
like beads on a string. Using this ordering, 
you can translate points of the 2D region 
into values suitable for B-tree indexing. In 
other words, the space-filling curve turns 
a 2D problem into a one-dimensional 
problem. 

To approximate a space-filling curve, 
divide the area of interest into small 
squares (cells) and place them in some 
predetermined order. Figure 2 shows three 
successively detailed approximations of 
the well-known space-filling curve in- 
vented by David Hilbert. The Hilbert curve 
is the limit of the infinite sequence of these 
approximations. To distinguish between 
an infinite space-filling curve and a finite 
approximation of it, I use the term “spa- 
tial ordering” for these approximations. 

To use a B-tree for spatial indexing, use 
the spatial ordering to convert 2D attributes 
into a one-dimensional “spatial key.” The 





spatial key is just a number that reflects 
the position of the cell within the spatial 
ordering. Figure 3(a) shows the number- 
ings of the cells in a Hilbert ordering. 


Designing and Creating the Database 
When you design the database, first di- 
vide the region into small cells. There is 
more than one way to do this, but the 
most common employs a “quadtree” hi- 
erarchy. Assuming the region to be di- 
vided is a square, a quadtree divides the 
square into four smaller squares equal in 
size. Each of those squares is further di- 
vided into four still smaller squares. The 
division process is repeated recursively 
until the cells are appropriately small. The 
end result is a grid of cells. Figure 2 shows 
the first, second, and third steps in this 
process. 

Next, put the grid cells into some or- 
der. Figure 3 shows three possible or- 
ders—row order, Morton order (also 
called “Z-order”), and Hilbert order (based 
on the Hilbert curve). Row order suffers 
a serious disadvantage because it is not 
based on a hierarchy such as a quadtree. 
Morton and Hilbert order are both based 
on a quadtree hierarchy, so they are nat- 
ural allies for grid cells derived from a 
quadtree. 

Finally, number the cells according to 
the spatial order. Assign number 0 to the 
first cell in the ordering, number 1 to the 
second cell, and so on. Figure 3 shows 
the cells numbered according to Hilbert, 
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Morton, and row orders. These numbers are 
the spatial keys— the one-dimensional at- 
tribute that will be indexed by the B-tree. 

How small should the cells be? As small 
as you can make them without over- 


flowing the integer size for the spatial 





keys. If the spatial keys are unsigned 32- 
bit integers, then you can divide the 
quadtree to a depth of 16; you will need 
every possible 32-bit integer value to as- 
sign each cell a number, but you will have 
enough values. 


Example 1: Two queries. (a) One-dimensional query handled efficiently by 
B-tree; (b) two-dimensional query is less efficient. 
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The numbering of the cells is cast in 
stone at design time. Once you’ve stored 
spatial keys in the database, the query ca- 
pability will work only if it assumes the 
same numbering scheme. 

When you create your database table 
of points, include a column to contain 
this spatial key, which I will refer to as 
skey. The database will have a B-tree in- 
dex on the skey column, which you must 
be careful to update every time you in- 
sert a new item or change the coordi- 
nates of some entry. 


Query Time 

When a buyer wants to see a map of avail- 
able homes in a particular area, the soft- 
ware first determines which cells lie com- 
pletely or partially inside the area of 
interest (called the “query region”), then 
constructs a query asking for the houses 
with the corresponding skeys values. This 
returns all the houses in those cells. Be- 
cause some of the cells were partly out- 
side of the query region, the final step is 
to filter out the houses that lie outside of 
the query region. 


An Implementation 

The querykanges function given in 
space.h and space.c (available electron- 
ically; see “Resource Center,” page 5) ac- 
cepts a Box structure containing the lat- 
itudes and longitudes of the boundaries 
of a rectangular area. The function re- 
turns a list where each item is a range of 
keys. The keys are grouped into ranges 
because the number of keys could be 
large enough to cause performance 
headaches and certainly much larger than 
you could expect the DBMS to deal with. 
Each range of keys includes a beginning 
key and an ending key. Any house with 
a key equal to the beginning key or the 
ending key of a range, or any key value 
between the two, should be retrieved 
from the database. 

The queryRanges function is designed 
to be used both for searching (when you 
need to know all the keys in a large area) 
and updating a single record (when it 
computes the key for a particular loca- 
tion). In the latter case, the two points in 
the Box structure are the same. Figure 4 
shows a query region with its ranges of 
Hilbert keys and the equivalent SQL. 


Performance 

Computing the spatial keys does not pre- 
sent a major performance issue. Rather, the 
question is how fast the database server can 
retrieve the data using the spatial keys you 
have computed. Two things determine the 
speed of retrieval when using spatial keys: 


e The number and complexity of the 
queries sent to the server. 
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e The amount of data read from disk and 
transmitted to the client program. 


ona nden sien angst When Visual Basic 
isn't powerful enough... 


query, it begins by parsing it and creating 
a plan for executing the query. For spa- 
tial queries, more ranges lead to more 
query overhead, because each range in- 
volves some overhead in query compila- 
tion and in accessing the index. 

On the other hand, more ranges mean 
less data read from the disk. Ranges of 


e @ e 
When C-+-+ Is too rigid... 
spatial Keys are a way of describing the 
ve eg Meebertoore oer When Java falls short ... 


ways include all of the original query re- 
gion so as to include all of the desired 
data, but it may include some undesired 
data. More ranges provide a tighter, more 
accurate description of the query region 
and the retrieval of less undesired data. 
Fewer ranges reduces the query overhead. 

Clearly, what you want is a good trade- 
off between the number of ranges and the 
accuracy of the region represented by 
those ranges— a continuous space-filling 
curve offers the best trade off. 





When your software dreams have gone beyond the 
capabilities of your programming language, you 
need the dynamic object tools provided by 
Common Lisp and Allegro CL". 








Morton versus Hilbert 

Figures 4 and 5 show ranges computed 
with the discontinuous Morton curve and 
the continuous Hilbert curve; space.h and 
space.c implement both. The compile-time 
constant, HILBERT, enables the Hilbert im- 
plementation. 

In general, the number of ranges is pro- 
portional to the length of the boundary of 
the query region. When the Hilbert curve is 
used to produce ranges for a rectangular 
query region, the number of ranges averages 
about (W+H)/2, where Wand H are di- 
mensions of the rectangle in units equal to 
the width of the cells. For the Morton curve, 
the average is closer to W+H. The jumps in 
the Morton curve explain this difference. 

Though Hilbert clearly performs better, 
some say that the additional complexity 
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Figure 1: The blue shows the area 
whose data is read from disk when a 
query like Example 1(b) uses a B-tree 
index on longitude to retrieve data in 
the small rectangle. 






* As experienced by several of our clients. 
Allegro CL® is a registered trademark and “The Leader in Dynamic Objects” is a trademark of Franz Inc. All product names 
referenced herein are trademarks of their respective companies. 







Dr. Dobb’s Journal, July 1999 117 








is not worthwhile. Presumably, it is too hard 
to code. You can decide for yourself by 
looking at the C code where the compile- 
time constant is used to enable/disable the 
Hilbert curve. 


Large and Small Query Regions 
A space-filling curve is like a fractal; it 
has the property of self-similarity, that 
is, if you zoom in, you find that the de- 
tails look a lot like the big picture. This 
property gives a spatial ordering ob- 
tained using a space-filling curve an im- 
portant advantage over a spatial order- 
ing that is not based on a space-filling 
curve, such as row order illustrated in 
Figure 3(c). The methods outlined so far 
will work well when all of the query re- 
gions are roughly the same size. How- 
ever, if the spatial ordering is not based 
on a space-filling curve, queries of great- 
ly varying size would present problems. 
Large queries would require large num- 
bers of ranges, resulting in poor perfor- 
mance. 

The number of ranges on average is 
proportional to the perimeter of the query 


region. Suppose the cells are 100 meters 
across. A query 1 kilometer long and high 
will require 10 ranges on average. That’s 
okay. A query 20 kilometers long and high 
will require 200 ranges on average. That’s 
not so good. Suppose the query is a query 
for airports. Users would not expect much 
data to be retrieved so they wouldn't ex- 
pect the query to take long. But 200 ranges 
will entail a significant amount of over- 
head in database processing. 

However, because space-filling curves 
are based on a hierarchy (a quadtree hi- 
erarchy in the case of the Hilbert and Mor- 
ton curves), they offer a solution. The 
quadtree hierarchy includes cells of vary- 
ing size. Each leaf cell is assigned a sin- 
gle key. Each higher-level cell corresponds 
to a single range of keys. 

Figures 4 and 6 show how you can use 
this relationship between the curve and the 
quadtree to generate about the same num- 
ber of ranges regardless of the size of the 
query region. The query region in Figure 
4 is covered by three ranges. Figure 6(a) 
is a larger query region with seven ranges. 
Figure 6(b) shows the same query but with 


leaf cells aggregated into cells twice as wide 
and high to reduce the number of ranges. 
The number of ranges is about the same 
as for the smaller query of Figure 4. 

You pay a small price for this benefit; 
the excess area covered by the aggregat- 
ed ranges is greater than if the aggrega- 
tion is not used. The ranges include cells 
that do not overlap the query region. How- 
ever, you choose depth to keep the ex- 
cess roughly in proportion to the area of 
the query region, so the overall solution 
is acceptable. 

Regardless of the size of a query region, 
it can be represented with reasonable ac- 
curacy by a reasonable number of ranges 
without any change to the keys in the 
database. 

The depth parameter of queryRanges is 
used to control the amount of aggrega- 
tion. It says how far down in the quadtree 
hierarchy to go, that is, what size cells to 
use when generating ranges. The highest 
level cell in the hierarchy is at level 0. If 
depth is 3, then querykanges will descend 
three levels to cells that are 1/8 as wide 
and high as the top-level cell. In Figures 





Figure 2: (a) First approximation of the Hilbert curve; (b) second approximation of the Hilbert curve; (c) third 


approximation of the Hilbert curve. 





Figure 3: (a) Spatial keys based on row order; (b) Morton keys; (c) spatial keys based on the Hilbert curve. 
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(continued from page 118) 
4,5, and 6(a), depth is 3. In Figure 6(b), 
depth is 2. 


How queryRanges Works 

The function gueryRanges calls the re- 
cursive function subtreeRanges, which 
does the real work. The subtreekanges 
function explores the quadtree of cells to 
find cells that overlap with the query re- 
gion. The recursion begins with the top 
quadtree cell, which is passed to sub- 
treekanges by queryRanges. 

When called, subtreeRanges compares 
two regions, the query region represent- 
ed by the structure *pQuery and the 
quadtree cell represented by the structure 
*pCell. The Box structure is used to ex- 
press the rectangular limits of both the 
cells and the query region. If the query 
region and the cell do not overlap, sub- 
treeRanges returns without doing anything. 
If they do overlap, then one of two things 
will happen: 


e If the level of the cell is less than the 
level given by the depth parameter (that 
is, the cell is higher in the quadtree than 
the lowest cells to be looked at by sub- 
treekanges), then subtreekanges con- 
structs the four child cells of the cell and 
calls itself four times to explore the sub- 
tree for each child cell. 

e If the level of the cell is equal to or 
greater than depth, then the subtree will 
not be explored. Instead, subtreeRanges 
computes the range of keys for the cell 
and adds that range to the list of ranges 
at *pRangeList. If the cell is a leaf cell, 
then the range will consist of a single 
key. (The constant DEPTH determines 
the leaf depth.) 
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SELECT * FROM homes WHERE 
(skey >= 6 AND skey <= 11) OR 











(skey >=53 AND skey <= 54) OR 
(skey >= 57 AND skey <= 57) 


Figure 4: A query (dashed line) with 
three ranges of Hilbert keys (three 
colored regions) and SQL to retrieve 
data in those ranges. 
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To compute the lowest and highest keys 
within a cell, first look at the relationship 
between a key and the quadtree. Each lev- 
el in the quadtree hierarchy corresponds 
to two bits in a key. The highest two bits 
specify one of the four cells at level 1. The 
next highest two bits specify the level 2 
child of the level 1 cell, and so on. The 
lowest order two bits picks one leaf cell 
out of four. These relationships hold for 
both Morton and Hilbert orderings. 


A space-filling curve 
is like a fractal 


The structure Ce// contains a field, 
keyPrefix, that contains the bits that are 
common to all keys for cells in the sub- 
tree of the cell. Each of the subtree keys 
can be generated by shifting kReyPrefix 
to the left and filling in the low-order 
bits. But you only need the first key and 
the last key in the range of keys. The 
first key is just keyPrefix shifted left, the 
low-order bits set to 0. The last key can 
be computed by adding the total num- 
ber of keys within the cell to the first 
key and subtracting 1. The number of 
keys within the cell is simply a power 
of 4. At the leaf level, it is 1. One level 
above that it is 4, and two levels above 
it is 16. The power of 4 is easily com- 
puted with a shift. 

So shifts and adds are all that are need- 
ed to compute the range from the cell’s 
depth and prefix. In addition, you need 
to compute a child’s prefix from the par- 
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Figure 5: The same query as Figure 4 
but with Morton keys. Now there are 
five ranges. 





ent’s prefix. That is done by shifting the 
parent prefix left two bits and adding the 
two bits for the child cell. 

When using Morton order, it is as sim- 
ple as that. For Hilbert order, all of this 
applies, but additional complexity arises 
from the changing orientations of its ba- 
sic U shape. The Morton order is built 
from Z shapes that all have the same ori- 
entation. The U shape in a Hilbert order- 
ing is rotated into various positions — 
sometimes on its side and sometimes 
upside down— to maintain continuity. 

To deal with these rotations, the rela- 
tive order of four sibling cells in the Hilbert 
order is computed and stored in the local 
array hilbertOrder, which is used to com- 
pute the key prefixes for the cells. Two 
static tables are used to compute the or- 
dering stored in hilbertOrder. The table 
hilbertIndexTable provides the position of 
a cell among its siblings given its position 
among its sibling in the Morton order and 
the orientation of its parent's U shape. The 
table bilbertRotationTable provides the 
orientation of the cell’s U shape given that 
of the parent and the cell’s position among 
its siblings. 

Admittedly, the code for Hilbert is tricky, 
but it’s not much code for the benefit 
yielded. 

As Figure 4 illustrates, a range of keys 
need not correspond to a single quadtree 
cell. Some ranges consist of several ad- 
joining cells. Because you want to mini- 
mize the number of ranges produced by 
querykanges, you want to ensure that one 
range is produced in such cases, not sep- 
arate ranges for each cell. This is achieved 
by taking advantage of the fact that 
queryRanges visits cells in order of their 
appearance in the spatial ordering and the 
fact that ranges are consequently placed 
in the range list in ascending order. When 
a range is added to the list, it is compared 
with the last range added to the list. If 
there are no intervening key values be- 
tween them, the two ranges are combined 
into one range representing exactly the 
same set of cells. The order of visitation 
ensures that no opportunities to combine 
will be missed. 

The difference in effectiveness between 
the Morton and Hilbert orders arises in the 
combining of ranges. For Hilbert, ranges 
will be combined much more often. 


Application in an RDBMS Environment 
These techniques can be used to provide 
spatial indexing for spatial objects stored 
in a relational database that provides only 
B-trees for indexing. Of course, there are 
some practical issues to consider. 

The natural way to turn a set of ranges 
into a SQL query is to use the SQL OR 
operator to combine the ranges in a sin- 
gle SQL query. However, many database 
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Figure 6: (a) With depth=3, seven ranges are produced for this query; (b) same 
query as (a), but with depth=2. This causes queryRanges to lump four small cells 
into one large cell. As a result, there are only three ranges. 


query engines will fail to use the B-tree 
index on the spatial key when present- 
ed with a query like this. However, they 
will do the right thing when presented 
with several SQL queries combined into 
a single query with the UNION opera- 
tor. The effect is the same, except that 
failure to use the B-tree would result in 
incredibly bad performance. 
Conceivably, some database engines 
will choke if presented with too many 
ranges in a single query (whether using 
the OR or the UNION operator). It may 
then be necessary to either reduce the 
number of ranges or use multiple queries, 
each with a small number of ranges. 


Possible Extensions 

The techniques I’ve outlined here are suit- 
able for many applications, particularly 
those in which the objects are points. For 
wider application, there are many possi- 
ble extensions, for example, support for 
lines and areas as query regions or 
database objects. Some applications may 
require keys longer than 32 bits to ensure 
adequate resolution when the database 
has densely packed objects in a large 
space. Other optimizations can be imple- 
mented to produce better results using 
fewer resources. 

Some applications may have 3D re- 
quirements. For example, imagine a 
database of crimes with locations and 
times. A query to retrieve crimes in a par- 
ticular neighborhood during a particular 
week would call for the indexing of a 3D 
space with two dimensions of space and 
one dimension of time. The space-filling 
curves would wind through this 3D 
space. 


Other Applications 


Space-filling curves can do more than 
query regions. They are handy for “spa- 
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tial clustering,” ordering the data on disk 
by spatial key so it can be scooped up 
quickly once your spatial indexing tech- 
nique has located it. So even when the 
database server has an R-tree built in 
(the ideal), space-filling curves can play 
a role in the retrieval of the data. Space- 
filling curves are useful even inside the 
R-tree. A variant of the R-tree called the 
“Hilbert R-tree” uses the Hilbert curve to 
help maintain spatial organization with- 
in the tree. 

Another operation used in spatial 
databases is the spatial join that locates 
pairs of objects with some common spa- 
tial attribute (for instance, they are with- 
in one mile of each other). Usually, the 
objects come from two tables. Sorting the 
two tables by spatial key facilitates the 
search. 

Farther afield, space-filling curves have 
been proposed for solving a problem 
known as the “Planar Traveling Salesman 
Problem,” which asks you to choose an or- 
der for visiting a number of points in a plane 
so that the total distance traveled is mini- 
mized. It is expensive to compute an opti- 
mal solution, but a very inexpensive solu- 
tion is to visit the points in the order they 
appear on a space-filling curve. After find- 
ing an approximate solution quickly, known 
algorithms can improve on the solution. 

Other possible applications include 
compression of raster images and dither- 
ing— a graphics technique that mixes pix- 
els of varying colors and shades to give 
the illusion of colors and shades not sup- 
ported by the display. 
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Flats and Steeps 


Dennis E. Shasha 


@ewhe journalist Cloe Anne Bennet ex- 
_ plained, “It’s the strangest mathe- 
| matician story I’ve ever written. A 
| group of brilliant mathematicians 
form an association, the Borghese Club, 
dedicated to mathematical games in- 
spired by the construction techniques of 
the Renaissance and Antiquity. Each year, 
they meet in Rome. They walk together 
through the stone arches and post-and- 
beam construction of the Imperial Fo- 
rum; then the two-thousand year old 
Colosseum built to hold 50,000 specta- 
tors and hundreds of animals and glad- 
iators; and finally that jewel of the Re- 
naissance— the Villa Borghese. Walking 
among the paintings of Caravaggio and 
the sculptures of Bernini, they exchange 
game proposals, until one wins, usually 
by consensus.” 

Ecco nodded. “They have invited me 
several times. But something always comes 
up: a kidnapping, a trial, a criminal. You 
know, my normal lot,” he said with a smile. 

“That’s okay,” Bennet responded. “This 
year, the game has come to you. The 
Borghese Club has invented a series of 
games based on the principle of columns 
and beams. They call it ‘Flats and Steeps.’ 
It is played on a grid of dots. The presi- 





Dennis, a professor of computer science at 
New York University, is the author of The 
Puzzling Adventures of Dr. Ecco (Dover, 
1998), Codes, Puzzles, and Conspiracy 
(W.H. Freeman & Co., 1992), Database 
Tuning: A Principled Approach (Prentice 
Hall, 1992), and (coauthored with Cathy 
Lazere) Out of Their Minds: The Lives and 
Discoveries of 15 Great Computer Scien- 
tists (Springer Verlag, 1998). He can be 
contacted at DrEcco@ddj.com. 
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dent, Maurizio Ferro, sends you the de- 
scription with his compliments. 

“Here is the simplest version called 
‘Straight Flats and Steeps’: 


1. There are two players who alternate 
moves until one player cannot move. 
The winner is the player who makes 
the last move. 

2. A move of the first player consists of 
drawing a flat (a horizontal line seg- 
ment connecting two adjacent dots). A 
move of the second player consists of 
drawing a steep (a vertical line segment 
connecting two vertically adjacent dots). 
The first player is called ‘Flats,’ the sec- 
ond ‘Steeps.’ 

3. A player’s line segment may not touch 

a dot touched by a segment previous- 

ly drawn by his opponent. Nor may a 

player draw a line segment between 

two dots that already have a line seg- 
ment between them. 


Figure 1: Playing the “Flats and Steeps” game. 








“Figure 1 shows how a game on a 4x4 
grid might evolve. 

“Now, the first player (the one play- 
ing Flats) has two moves and so does 
the second player (Steeps). Neither can 
prevent the other from making those 
moves. After they are over, Flats will be 
the first one who can’t move and so los- 
es. Here’s the first question the Borgh- 
ese Club poses to you, Ecco: Does ei- 
ther player have a winning strategy on 
a 4x4 grid?” 

Liane entered the fray, “A winning strat- 
egy means being able to force a victory, 
right uncle?” 

Ecco nodded. “Right. No matter what 
the other player does, one player should 
have a strategy for winning,” he re- 
sponded. 

Liane thought about this for some time, 
“Well, then, I think the first player should 
be able to win,” she said. “The first play- 
er’s first Flat move should be here.” 
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She drew a line segment between two 
points of an empty grid. 


Reader: Can the first player, in fact, force 
a victory with the right strategy? If so, how? 
If not, why not? 


Cloe Anne Bennet smiled at the 11- 
year-old girl. “That was fast,” she said. 
“Tll check whether or not they agree with 
you. Given your reputation, I suspect 
they will. 

“In the meantime, they have a second 
variant called ‘Articulated Flats and Steeps’ 
that modifies ‘Straight Flats and Steeps’ in 
two ways: 






















Figure 2: (a) Flats goes first; (b) Steeps responds as a dotted green line; (c) Flats 
makes a steep move. This is allowed by articulation; (d) Steeps is allowed to 1. (Articulation) Each player may draw 
make one isolated flat move (as well as any number of articulated flat moves). a line segment A in any direction if he 
or she already has a line segment A’ 
touching one of the endpoints of A 








(it doesn’t matter whether that player 

f Or C/ C++ has another line segment A” touching 

; : the other endpoint of A). Thus, the 
-lant Version iD Flats player may make steep moves 
presents Bug # 140] provided the resulting line segment 


attaches to at least one dot previous- 
ly touched by Flats and neither end- 
point is touched by a segment of 
Steeps. The same applies symmetri- 
cally for Steeps. 

2. (Compensation) To compensate for 
the disadvantage of going second, 
Steeps may draw up to one flat line 
segment anywhere he likes, provided 
neither endpoint is touched by a seg- 
ment of Flats. 


#include <iostream.h> 
class Point { public: double x, y; }; 
class Circle { public: Circle(); Point ctr; double r; }; 
Circle::Circle() :ctr(),; r(0.0) { } 
bool intersect_with_x( const Circle &c ) 
{ 
if( c.ctr.y > c.r || c.ctr.y < -c.r ) return false; 
else return true; 
} 
int main() 
{ 
Circle origin; 
char *s = intersect_with_x( origin ) ? "" ;: "not "; 
cout << "The origin does " << s << 
"intersect with the x axis\n"; 
return 0; 


} 


“Figure 2 illustrates all of this. The 
moves of Steeps are represented by 
green dotted lines. Note that Flats makes 
a steep move in Figure 2(c), and Steeps 
makes an unattached flat move in Fig- 


Defying all principles of Geometry and Trigonometry this program proclaimed that ure 2(d). 

the origin does not intersect with the x axis. Where's the bug? Call if you need a “Their question is: Which player can 

hint or visit our web site at www.gimpel.com force a win of ‘Articulated Flats and Steeps’ 
PC-lint for C/C ill catch this and Plus Our Traditional C/C++ Warni os disee he 

-lint for ++ will catch this and man us Our Traditiona ++ Warnings: 
other bugs. It will analyze a mixed suite of C Uninitialized variables, inherited onal . To wes eel bel neither Ecco nor 
and C++ modules to uncover bugs, glitches, destructors, strong type mismatches, Liane came up with a solution before I 
quirks and inconsistencies. ill-formed macros, inadvertent name-hiding, left, although Ecco developed a strong 
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rigorously checked. Numerous compilers/ libraries supported. a very clever lot, I suggest a collective ap- 
Version 7.5 pushes the envelope of lint Se ont ARGON oe OWS Ne roach to “Articulated Flats and St is 
san eg | DOS (built-in DOS extender), and OS/2. is ee ae 

detection still further. User-defined semantic 30 day money back guarantee. If any reader would like to set up a web 


checking of functions offers a unique language 


to express argument constraints, inter-argument FlexeLint fe or C/C++ site that will p a Java dc 


relationships, and return values. There are 75 The same great product for other operating grams to play or b A p lay ets to play, 
new messages including cradle-to-grave systems. Runs on all Unix systems, VMS, the DDJ web page will give pointers to 
checking of pointers and the latest admonitions mainframes, etc. Distributed in shrouded the sites after I check them out. As win- 
and perorations of Scott Meyers. C source form. Call for pricing. ning strategies emerge, I will report the 
a results in future columns. Eventually, we 
G | rn 08 Softwa re may evolve to variants that allow diag- 
3207 Hogarth Lane, Collegeville, PA 19426 onals (Flats, Steeps, and Slopes) and to 

CALL TODAY (610) 584-4261 Or FAX (610) 584-4266 
www.gimpel.com Dr. Dobb's Journal, July 1999 


PA add 6% sales tax. PC-lint and FlexeLint are trademarks of Gimpel Software 


strategies for multiplayer versions, but 
for now please let’s stay with “Articulat- 
ed Flats and Steeps” of size 4x4 and larg- 
er squares. 


Last Month’s Solution 
Figure 3 illustrates the solution to the June 
1999 “Fitting” problem. 


Reader Solutions to the 

“Joints in Space” Problem 

The following readers matched or im- 
proved upon Dr. Ecco’s solution to the 
“Joints in Space” problem (DD/J, April 
1999): Burghart Hoffrichter, Earl Paddon, 
Pearl Pauling, Jean-Francois Halleux, and 
Alan E. Dragoo. 

Alan’s solution was the best I’ve re- 
ceived so far. Whereas Ecco was able to 
establish 34 adjacency guarantees, Dra- 
goo’s solution was able to establish 15 
additional ones. His design involved 5 
levels. The first was 4x3 but with three 
missing blocks. The second was 4x3. 
The third was 4x3. The fourth was 3x3 
with an extra block. The fifth was 5x2 
with many gaps (5 blocks in total). 
Clever guy. 


DDJ 
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Figure 3: Solution to the “Fitting” problem (DDJ, June 1999). 


Paul Sheriff has 10 years wee experience a a top instructor 
and lecturer. He owns his own programming shop in southern 
California and his experience enables him to teach you with real- 
world instruction. John Hawkings, CEO of Advisor Media, says, 


“Paul Sheriff is the best! Learn the eae lial _— 
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Linux Sysadm 


On Your Own 
Jett Taylor 


Ithough I have years of experience 

with UNIX, I’m still a relative new- 

comer to Linux. I am not new to net- 

worked PCs. What I am new to is the 
level of involvement that Linux allows and 
even rewards. However, the installation and 
configuration books I own don’t go into 
enough detail about networking. Nor do 
the HOWTOs give enough of an overview 
or coordinate well with each other. Conse- 
quently, the Linux Network Administrator's 
Guide, by Olaf Kirch, is just what I need to 
keep my home network running. It is a 
book for anyone who needs to administer 
a small Linux network or networked Linux 
workstation, but is not a full-time network 
administrator. 

Don’t let the most recent printing date 
(1995) scare you off. No, it doesn’t cover 
IPv6, but then my ISP doesn’t require or 
support it and I expect yours doesn’t either. 
Face it, the basics of networking have been 
around for years. Yes, the cutting edge is 
changing constantly. If you are working at 
the cutting edge of networking, you don’t 
need this book. Still, the areas where the 
book does show its age involve: 


e Kernel versions discussed (1.0 and 1.1.14). 

¢ No mention of twisted pair Ethernet 
(10Base-T), although it covers thin wire 
(10Base-2) and thick wire (10Base-5) 
Ethernet. 

e More emphasis on Serial Line IP (SLIP) 
than on Point-to-Point Protocol (PPP). 

e No mention of Samba (file and printer 
sharing with Windows 95/NT). 


Easing into Linux is a problem. It some- 
times seems like you have to know it all 
before you can work with any of it. An 
approach that works for me is to read a 
manual or book until it starts running out 
my ears, then do some of the obvious 
things. Once I have some idea what’s go- 
ing on, I reread the book. While reading, 
I flag things to do. With Linux Network 


Jeff is currently taking a sabbatical to re- 
search Linux and software development pro- 
cesses. He can be contacted at jeff-taylor@ 
leee.org. 
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Administrator's Guide, I flagged 13 places 
in the first 130 pages. 

The first three chapters are background. 
Chapter 1 introduces UNIX-to-UNIX Copy 
(UUCP) and TCP/IP networks. Though 
UUCP can be done over TCP/IP as well as 
dial-up lines, its main feature is that it queues 
up e-mail, news articles, and files to be trans- 
ferred or printed and sends them in a batch 
at a later time. UUCP dates from the late 
1970s, when high-speed modems ran at 
1200 bps and the Internet was the Arpanet 
and a research vehicle. I am ambivalent 
about using UUCP. Is a home computer with 
dial-up access to an ISP or a laptop occa- 
sionally connected to a network suitable for 
UUCP? So far, I don’t think so. Still, it is nice 
to have the option covered, even if I don’t 
choose to go that route. 

Chapter 2 goes into TCP/IP networks in 
more detail. Kirch introduces an example 
network for the hypothetical Groucho Marx 
University. The net topology figure on page 
24 shows three subnets connected to the 
campus backbone. It shows clearer than 
any thousand words why IP addresses be- 
long to network adapters, not computers. 
A gateway computer connecting a subnet 
(that is, a home network) to a larger net- 
work (an ISP) has IP addresses for each 
connection, and they can be different. Un- 
fortunately, there is a typo in this, and the 
diagrams don’t match the text. The IP ad- 
dress on the backbone side of the Com- 
puting Center gateway should be 1.2, not 
1.1. In the domain name space example 
(Figures 2 and 3 on page 28), the .maths 
domain is not a zone and the circle next to 
it should be deleted. 

Chapter 3 (“Configuring the Hardware”) 
is about the kernel and device drivers. Many 
writers emphasize that you must build your 
own custom kernel. I have successfully 
avoided this up to now. The advent of load- 


http://www.dg) 


Electronic Review of 
Computer Books | 





able device-driver modules and inexpen- 
sive memory alter the necessity to rebuild 
the kernel. Low-level functionality such as 
device drivers can usually be put in a load- 
able module. The memory regained by 
deleting unused features is insignificant for 
today’s typical PC. Linux is efficient in its 
memory usage and runs well with a single 
user in 20—40 MB, though it can run in 8 
MB (4 MB without the X-Windows system). 
Over time, the repeated exposure to how 
to build a custom kernel is acclimating me 
to the idea. 

Chapter 5 (‘Configuring TCP/IP Net- 
working”) is where I really started to flag 
things. Kirch introduces the Virtual Brew- 
ery network example used through the rest 
of the book. It starts simply— just a private 
network with two subnets and a gateway 
computer between them. After describing 
how to setup the permanently connected 
part, Kirch adds a laptop with a point-to- 
point link to the gateway computer. The 
example uses a Parallel Line IP (PLIP), 
TCP/IP through the parallel port. There are 
two other point-to-point protocols in com- 
mon use, Serial Line IP (SLIP) and Point-to- 
Point Protocol (PPP). They are more com- 
plex and are covered in separate chapters. 
The last four pages cover tools for check- 
ing your network configuration. I really ap- 
preciate this. It is nice to see how the con- 
figuration commands were interpreted and 
what the current configuration is. I hate the 
write-only registers in some hardware where 
there is no way to find out about a previ- 
ous program or invocation set. Gurus on 
communication between people tell you to 
paraphrase back to the other person what 
you understood them to say, to ensure you 
both have the same understanding. This is 
good advice for computer programs, too. 

Chapter 6 is on “Name Service and Re- 
solver Configuration.” The resolver is the 
part of the Linux C libraries that combines 
the /etc/hosts file contents and the Domain 
Name Service (DNS) results to map host 
names to IP addresses and vice versa. Oth- 
er books cover these parts separately. What 
makes this book so uniquely valuable is the 
explanation of how they interact. I had been 
having problems with host name lookup. 
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What worked when my computer was off- 
line didn’t work when I was online with the 
ISP, and vice versa. I was using the ISP’s 
domain name for my home network’s do- 
main name. This is wrong. Instead, pick 
something unique and ping it while online 
to make sure no one has registered it (the 
name lookup will fail). My first choice was 
registered but not in use (the host lookup 
succeeded, but the ping wasn’t returned). 
I also needed the “trim <domain.name>” 
directive in the /etc/resolv.conf file. 

The sections on setting up DNS is of in- 
terest to anyone with their own domain, re- 
gardless of whether they or their ISP man- 
ages the DNS server. I find it helpful to 
understand DNS even though I don’t (yet) 
have my own domain name. 

Kirch also covers resolver and DNS set- 
ups that seem reasonable and yet give 
strange results. I like this. Knowing what 
not to do and why is often more valuable 
than a cookbook style “just do this.” The 
chapter concludes with a section on how 
to check the operation of name server set- 
up. Again, I like knowing how to check that 
what I said was also what I meant. 

I considered using SLIP to connect my 
laptop to my desktop. Most books on SLIP 
assume you are using a dial-up line. Chap- 
ter 7 (‘Serial Line IP”) also covers a plain 
serial link and tells how to change the ad- 
vice in the previous chapter to accommo- 
date dial up. This book is good about links 
forward and backward to itself and to HOW- 
TOs and Internet standards (RFCs). Some 
aspects of SLIP are common to PPP and are 
covered in the following chapter. Kirch cov- 
ers security aspects of SLIP connections, a 
topic missing in other books. While I was 
reviewing this book, the Melissa virus and 
its clones were released, a Linux-specific 
worm was found in the wild, and my com- 
puter’s network ports were scanned and tel- 
net connections attempted through the PPP 
connection to my ISP by several would be 
intruders. I am sure this kind of thing went 
on while I was running Windows 95 and I 
never knew. Prior to reading this book, I 
had used the ISP, Ethernet, NET-3, and PPP 
HOWTOs. I was able to get dial-up to my 
ISP working with these. After reading the 
chapter on PPP (Chapter 8), I understand 
what is going on, how PPP can go wrong, 
and what needs to be done to fix it. Good 
stuff. Also necessary when I added the sec- 
ond PPP link to the laptop. The ppp-go 
script that comes with Slackware 3.6 does 
a “killall pppd” so starting up the second 
PPP link would always kill the first. 

Chapter 9 (“Important Network Fea- 
tures”) — covers the inetd super server, tepd 
access control facility, and Remote Proce- 
dure Call (RPC) package. Rather than leave 
my system vulnerable to crackers until set- 
ting up a firewall, I set up a stonewall. I dis- 
abled all incoming ports by not running the 
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inetd daemon (Samba sets up its own dae- 
mons and doesn’t usually need inetd). This 
worked until I wanted to add the laptop to 
the network. I needed some way to com- 
plete the installation of various software 
packages besides a stack of floppies. With 
the tepd access facility, I allow the local ma- 
chines to do their thing without letting any- 
one in from outside. Other books and the 
HOWTOs only cover the “client” PPP side. 
This book covers the “server” side also. 

Chapter 10 covers “The Network Infor- 
mation System” (NIS), an intermediate step 
between all network information in con- 
figuration files and setting up your own 
DNS. From this chapter, you get an idea of 
what is involved in NIS setup and what it 
is useful for—a small LAN with all hosts 
permanently connected, occasionally adding 
or deleting hosts. This describes the usual 
LAN in an office and is generally not use- 
ful for a home network. Any network with 
Internet connectivity is going to have to use, 
if not configure, DNS. There is enough in 
this chapter to make an informed decision, 
but as Kirch notes, “If you want to run any 
of these packages, the instructions in this 
chapter may or may not be enough.” 

NFS is a way to share files between com- 
puters, principally Linux and other types of 
UNIX boxes. (Samba is a way to share files 
and printers between Windows and Lin- 
ux/UNIX boxes). There are problems with 
NFS that Kirch covers in Chapter 11 (“The 
Network File System”) and I have read di- 
atribes about NFS. Some are unique to Lin- 
ux circa 1995 and I expect have been fixed. 
Others are inherent in NFS. There are al- 
ternatives, such as the Andrew File System 
(AFS), but in my experience, the cure is 
worse than the cold. There is current work 
in this area (the Coda distributed file sys- 
tem, for instance). Stay tuned. Chapter 11 
tells how to setup NFS clients and servers. 
NFS looks like the way to share the CD- 
ROM drive on a desktop computer with a 
laptop to complete an installation started 
from floppies. 

Chapter 12 addresses UUCP, a suite of 
programs for storing and forwarding print 
jobs, e-mail, newsgroup articles, and other 
remote jobs. At first glance, UUCP looks like 
a holdover from the old days of isolated 
mainframes with dial-up at night when long 
distance rates are lower. But a laptop with 
a sometime connection to another computer 
has a lot of the same needs. Ian Taylor has 
done a more modern reimplementation of 
UUCP that has been ported to Linux. At 30 
pages, Chapter 12 is long, but setup is clear- 
ly explained, along with some of the details 
and protocols used under the hood. You 
will have enough information to setup a ba- 
sic installation and keep it running. 

Chapter 13 covers e-mail routing, both 
via UUCP and on the Internet, and the Elm 
text-based e-mail client. Having tried both, 


I find I prefer Netscape Navigator in the X 
environment for reading and writing mail 
while online with my ISP. However, it does 
not deal gracefully with composing mail off- 
line. I use Mutt, an Elm derivative, to dash 
off a quick idea that comes while offline. 
Kirch also covers UUCP e-mail routing. 

An e-mail client is not enough for Linux, 
even on a single-user system. Linux (like 
UNIX) allows setting up batch jobs that run 
at a specified time in the background. These 
may include UUCP dial in the dead of the 
night, software rebuilds, benchmarks on an 
unloaded system, or backing up a system. 
All of these generate output to the e-mail 
system. A Mail Transfer Agent (MTA) han- 
dles routing this e-mail to where the e-mail 
client expects to find it. Chapter 14 exam- 
ines Smail, an MTA suitable for small sys- 
tems. Kirch shows how to set up Smail for 
a TCP/IP environment, UUCP environment, 
and mixed TCP/IP-UUCP environment. I 
have seen HOWTOs and tips for both en- 
vironments, but this is the only place I know 
that covers both. Kirch tells what is going 
on under the hood in sufficient detail to be 
illuminating without drowning you in the 
minutiae. 

Estimates are that sendmail (covered in 
Chapter 15) handles 70-80 percent of the 
e-mail in the world and, as you might ex- 
pect, sendmail is a complicated subject. The 
sendmail book (also from O'Reilly) is over 
1000 pages. According to Kirch, “It’s been 
said that you aren’t a real UNIX system ad- 
ministrator until you've edited a sendmail.cf 
file. It’s also been said that you’re crazy if 
you do it twice.” Kirch is confident that the 
sendmail+IDA combination is usable by 
mere mortals and that even real sysadmins 
are more efficient with it. Even with the help 
of the IDA program, this is still tough stuff 
to wade through. Unless you are in train- 
ing to be a real sysadmin, Smail or the rel- 
atively new Qmail are a better way to go. 

Chapters 16 through 19 are short and cov- 
er newsgroups. I must admit that I just 
skimmed these chapters. I would rather let 
my ISP handle this and use Netscape to read 
them. My wife is the other user on our net- 


~ work and she uses AOL, not an ISP. There 


is no reason to have any newsgroups copied 
to our network for just one news reader. 
However, the sysadmin on my ISP does 
need this information, and I may need it for 
reference when something goes wrong. 

Linux Network Administrator's Guide has 
a permanent place on my bookshelf. With 
it, I can discard about half of the HOWTOs 
I used before I read this book. I would have 
been better served by reading this book first, 
then reading the PPP and ISP HOWTOs. 
The NET-3 and Ethernet HOWTOs are now 
redundant. I would rather have just this 
book than just the HOWTOs. 


DDJ 
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ask for free demo src avail visa/mc/c.o.d. 

















Don’t Throw Away Your dBase 


Files 


xBaseu is a collection of Java classes that reads, writes, 
and updates dBase III and IV dbf, dbt, ndx and max files. 
Only $95.00 and it’s royalty-free. 


www.americancoders.com 


American Coders, Ltd. 
Post Office Box 97462 
Raleigh, NC 27624 
919.846.2014 












Portable Embedded GUI 
Typical Config < 100KB 
VGA, LCD, Input Drivers 
Multitasking Version 
WindowBuilder RAD tool 
Font & Image Conversion 


Micro Digital Inc 
www.smxinfo.com/pegdd.htm 


System Software Outfitters 
(800) 366-2491 
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Call +1-513-425-8050 Fax 425-8025 
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Copy Protection « Electronic Software Distribution * License Management 


Features: 
* Wraps Your Software in Minutes 
* Try-Before-You-Buy & immediate Purchase 
* Software Metering & Rentals 
* Windows & Macintosh Compatibility 
* Foreign Language Support 
* Key Diskette Option 
Sales: (408} 297-7444 ext.} 
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The Best Try-Before-Buy Copy 
mace)icielile)amsareleiniiclcom mlerslarciiare 


CrypKey is solid, software-only copy protection with a 
broad range of features to control all aspects of your 
product’s operation. You can offer free one-time trials, turn 
demos into full multi-user network versions, or sell specific 
options by phone, fax or email. Sell usage by time, runs, 
features - the control is all there - easy to implement, and 
even easier to support; and it’s not fooled by reinstallation 
or back-dating. Imagine Internet distribution of your 
software with easy e-commerce features and automated 
authorizations without needing specialized equipment! 


C, C++, and JAVA DOCUMENTATION (v. 8.0) 


¢ C-CALL ($69)Graphic-tree of ¢ C-REF ($69)Creates cross-reference 
caller/called function hierarchy, cross- of local/global/define/parameter 
reference, file/function index. identifiers, class trees. 

¢ C-CMT ($69) ¢ C-DOC ($199) PACKAGE AI 5 
Creates/inserts/updates comment- programs integrated as 1 overall 
blocks (functions/identifiers used) for C-DOC program. <10,000 lines. 
each function. JavTREE graphic-tree viewer (Stree in 

e C-METRIC ($59) Calculates path C-DOC) 
complexity, counts lines with ¢ C-DOC Professional ($299) DOS, 
comments, code, 'C' statements. Win95/NT, OS/2, 1,000,000+ lines. 

¢ C-LIST ($69) Lists and action- 

e VERSION 8.0! 


diagrams, or reformats source into 

user-selected standard formats. 30-Day Money-back guarantee. 
SOFTWARE BLACKSMITHS INC. email @ swbs.com 
6064 St Ives Way, Mississauga _ Voice/Fax (905) 858-4466 
ONT Canada L5N-4M1 htto://www.swbs.com 
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Riverbed Technologies has announced an 
update to ScoutMTS v3.0, an enterprise 
platform for mobile computing data ex- 
change, integrating wireless and other 
handheld devices with mainstream enter- 
prise computing technologies. The 
ScoutMTS SDK leverages Microsoft COM 
to allow Windows developers to extend 
any application to a handheld device in a 
matter of hours. Other features include 
bidirectional information exchange, record- 
level synchronization, and automatic load 
balancing between multiple servers. New 
features include support for CE devices, 
an extended API, and advanced system 
management. The ScoutMTS suite runs on 
Windows NT; pricing begins at $995.00 
for the developer edition. 

Riverbed Technologies’ MobileArchitect 
is a graphical-design tool for developing 
PalmOS and Windows CE mobile systems 
for use in enterprise deployments. With 
MobileArchitect, you can paint the critical 
elements of an enterprise application (such 
as tables and forms) and then automati- 
cally generate client code for a number of 
environments, including SatelliteForms and 
CodeWarrior R5 for the PalmOS, and Vi- 
sual Basic and Visual C++ for Windows 
CE. MobileArchitect then generates the 
specified client and server code as well as 
a Riverbed Scout conduit for the target ap- 
plication. MobileArchitect includes the Mo- 
bileArchitect plugin API, an open and doc- 
umented API for creating customized 
plug-ins, wizards that generate applica- 
tion logic. The suggested list price for Mo- 
bileArchitect is $1795.00. 

Riverbed Technologies 

2070 Chain Bridge Road, Suite 475 

Vienna, VA 22182 

703-847-3303 

http://www.riverbedtech.com/ 


Reliable Software has released Code Co- 
op 2.0, a serverless version-control sys- 
tem for collaborative development. Code 
Co-op lets you perform standard version- 
control functions such as check-in, check- 
out, merge, and restore without a server 
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or network connection. Code Co-op 
works on a peer-to-peer network, but al- 
lows synchronization over e-mail or 
through the exchange of diskettes. The 
release of Version 2.0 automates distribu- 
tion of synchronization information. The 
e-mail distribution system works with any 
e-mail clients that support Simple MAPI. 
A single-seat license costs $150.00, with 
discounts for multiple seats. 

Reliable Software 

1011 Boren Avenue, Suite 206 

Seattle, WA 98104 

206-361-6679 


http://www.telisoft.com/ 


M Squared Technologies has announced 
Version 4 of its Resource Standard Metrics 
(RSM), a source-code metrics and quality 
analysis tool for C, C++, and Java for use 
on Windows NT/95/98 and UNIX systems. 
RSM performs metrics for lines of code 
(LOC), comment percentage, keywords, 
and constructs, logical and interface func- 
tional complexity, and class metrics. Ad- 
ditionally, RSM performs metrics on the 
function, class, file, project, and code tree. 
RSM can also run LOC metrics between 
two date-dependent code baselines yield- 
ing LOC and file differentials. Prices for a 
single user license start at $195.00. 

M Squared Technologies 

2128 Hidden Pine Lane 

Apopka, FL 32712 

407-880-2627 

http://www.m2tech.net/ 


LUCA 2.4 from Griffin Technologies is an 
upgrade to its universal communications 
components package. LUCA provides 
components for data communications and 
supports more than 50 different transport 
protocols. LUCA v2.4 adds encryption to 
every LUCA product package, support for 
VCL component technology for Delphi pro- 
grammers, and a new ActiveX control so 
Visual Basic programmers can use LUCA 
under Windows CE. Other new features 
include CAPI supplementary services, re- 
vised documentation, and support for the 
latest versions of the compilers. 

Griffin Technologies 

916 Massachusetts Street 

Lawrence, KS 66044 

785-832-2070 

http://www.griftech.com/ 


TeamQuest has announced TeamQuest 
Alert, a multisystem monitor with built-in 
performance evaluation assistance. Team- 
Quest Alert provides a visual summary to 
highlight both good and poor performance 
in a single display. When a potential prob- 
lem is identified, users can display key 
system indicators and user-activity reports. 


TeamQuest Alert is designed to run from 


a single location on Windows NT and on 
a variety of UNIX platforms. 
TeamQuest Corp. 
2410 3rd Avenue South 
Clear Lake, IA 50428 
915-357-2700 
http://www.teamquest.com/ 


Insignia Solutions has released Jeode 1.0, 
its implementation of Java for Windows 
CE/NT and Linux-based embedded sys- 
tems. Licensed by Sun Microsystems to 
deliver a clean-room Java-compatible vir- 
tual machine, Insignia developed Jeode 
using virtual machine technology that dy- 
namically optimizes the use of available 
system resources. 

Insignia Solutions 

41300 Christy Street 

Fremont, CA 94538 

510-360-3700 

http://www.insignia.com/ 


Data Junction has announced its Univer- 
sal Transformation Suite (UTS), a complete 
tool set for application integration, data 
migration, data replication, data cleansing, 
and data-mart projects on any platform. 
Data Junction UTS supports complex data 
structures with multiple record types and 
a graphical process flow designer for vi- 
sually designing complete transformation 
projects that incorporate a limitless num- 
ber of external procedures and programs. 
The product also incorporates event man- 
agement for sophisticated error handling 
and data-driven transformation logic. 

Data Junction Corp. 

2201 Northland Drive 

Austin, TX 78756 

512-459-1309 

http://www.datajunction.com/ 


Continuus Software has launched Web- 
Synergy 2, an update to its change man- 
agement software for web-based devel- 
opment and web content. WebSynergy 2 
features an enhanced Continuus Web Au- 
thor Component; WebSynergy Server, a 
commercial repository for managing com- 
plex web development environments and 
processes; task-based change management 
for web teams, task-based web workflow 
process, and task-based team coordina- 
tion. Representative pricing for a 25 mem- 
ber team is $59,995.00. 

Continuus Software Corp. 

108 Pacifica 

Irvine, CA 92618 

949-453-2200 


http://www.continuus.com/ 


Aonix Lifecycle Desktop from Aonix pro- 
vides you with a process-oriented ap- 
proach to complete lifecycle management 
of software applications. Aonix Lifecycle 
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Desktop meets development process 
mandates such as IEEE 12207 and DOo- 
178B. It offers immediate and customiz- 
able access to all lifecycle activities and 
artifacts, including requirements analysis, 
definition, management, code generation, 
lifecycle modeling and test specification, 
generation, and execution. Aonix Lifecy- 
cle Desktop is available for Windows NT 
and for UNIX. Pricing starts at $4500.00. 

Aonix 

5040 Shoreham Place 

san Diego, CA 92122 

619-457-2700 

http://www.aonix.com/ 


Zero G Software’s InstallAnywhere Now! 
is available to all software developers free 
of charge. InstallAnywhere Now! is the 
entry-level version of Zero G’s Java appli- 
cation installer that handles platform- 
specific details, giving you the ability to 
build multiplatform installers for distribut- 
ing software over the Internet or on CD- 
ROM. Its Project Wizard interface enables 
installers to be built in six steps. Install- 
Anywhere Now! automatically locates the 
application’s “main class” and properly con- 
figures the classpath. The tool also offers 
the ability to create double-clickable Launch- 
Anywhere application launchers with cus- 
tom icons. InstallAnywhere Now! is freely 
available for download from http://www 
javalobby.org/, Zero G Software’s web site, 
and other Java development resources. 

Zero G Software Inc. 

118 King Street, # 415 

San Francisco, CA 94107 

415-512-7771 

http://www.zerog.com/ 


Sybase’s SQL Anywhere Studio now in- 
cludes the UltraLite deployment option 
and MobiLink enterprise server synchro- 
nization technology for Windows CE and 
the 3Com Palm Computing platform. The 
UltraLite deployment option provides an 
application- optimized, ultra-small database 
that resides locally on handheld devices 
and embedded systems. MobiLink provides 
two-way server synchronization, enabling 
the UltraLite database on a handheld de- 
vice or embedded system to receive in- 
formation from and send information to 
an enterprise database. Suggested retail 
price for SQL Anywhere Studio is $399.00 
for one user or $999.00 for five users. 

Sybase Inc. 

6475 Christie Avenue 

Emeryville, CA 94608-1050 

800-879-2273 

http://www.sybase.com/ 


Reticular Systems has released Agent- 


Builder Pro 1.1, an integrated software 
toolkit that lets you develop intelligent 
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software agents and agent-based appli- 
cations. AgentBuilder Pro provides a 
number of tools for defining an “agen- 
cy’— a collection of agents that work to- 
gether. These tools let you define be- 
havioral roles for agents in an agency. In 
addition, tools are provided for graphi- 
cally constructing communications di- 
alogs or protocols that define the con- 
versations between agents. AgentBuilder 
Pro uses these protocols to automatical- 
ly construct the behavioral code required 
by the agents to implement a protocol. 
In addition, AgentBuilder Pro includes 
an Agency Viewer to monitor and dis- 
play inter-agent message traffic in real 
time. AgentBuilder Pro sells for $4995.00 
for a single-user developer license. Aca- 
demic licenses are available at signifi- 
cantly reduced prices. Reticular also pro- 
duces AgentBuilder Lite priced at $495.00. 

Reticular Systems Inc. 

4715 Viewridge Avenue, Suite #200 

San Diego, CA 92123 

619-279-9723 


http://www.reticular.com/ 


Visual SourceFormat 1.0 is a tool that re- 
formats C++ source code to any desired 
style. Released by Raleigh Group Inter- 
national (RGD), the tool works as either 
an add-in for Visual Studio or a stand- 
alone application. Visual SourceFormat 
automatically converts C++ code from 
any style to any other desired style. The 
tool comes with seven predefined styles, 
and you can define your own custom 
styles, specifying over 30 aspects of 
curly-brace placement, indentation, op- 
erator spacing, function spacing, paren- 
thesized expressions, control statements, 
and more. Visual SourceFormat 1.0 costs 
$399.00. 

Raleigh Group International 

5440 Atlantic Springs, Suite 115 

Raleigh, NC 27616 

919-878-3717 

http://www.sourceformat.com/ 


Anabasis has introduced a collection of 
software tools for C++ and Visual Basic 
developers that support a wide variety of 
scientific and numeric functionality, such 
as random-number generation for pseu- 
dorandom and quasirandom deviates, root 
solving, moments computation, integra- 
tion and optimization based on the 
method of Monte Carlo, and simulation 
capabilities useful for the calculation of 
Value-at-Risk and credit risk. These tools 
are typically used for the manipulation of 
matrices, various types of matrix decom- 
positions, computing financial rates, dis- 
count factors and forward rates in sever- 
al market conventions, and a market 
simulation library that can be used to gen- 
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erate interest rate curves. The libraries 
come with classical and modern algo- 
rithms, and you can extend these libraries 
with your own algorithms. 

Anabasis Corp. 

65 Front Street West, 0116 

Toronto, ON 

Canada M5J 1E6 

416-604-3475 


http://www.anabasis.com/ 


The 6th Annual Conference on the Pat- 
tern Languages of Programs (PLoP99) will 
take place at the Robert Allerton Park and 
Conference Center, University of Illinois 
at Urbana-Champaign Urbana, IL from Au- 
gust 15 through 18, 1999. PLoP brings to- 
gether people who share an interest in 
exploring software design patterns. For 
more information, see http://jerry.cs.uiuc 
.edu/plop/plop99/. 


Natural MicroSystems has announced Ver- 
sion 3.0 of its Fusion IP telephony system. 
Fusion 3.0 is available in the CompactPCI 
form factor (a ruggedized hardware plat- 
form) and supports the SPARC Solaris op- 
erating system and standard protocols such 
as H.323, MGCP, and SIP. Version 3.0 also 
supports IVR and T.37 fax capabilities, stan- 
dard vocoding algorithms (G.723.1, G.711, 
G.729a, MS-GSM, ETSI GSM), dual 
10/100Mb Ethernet interfaces for failover 
and multiroute support, and real-time fax 
support. 

Natural Microsystems 

100 Crossing Boulevard 

Framingham, MA 01702-5406 

800-533-6120 

http://www.nmss.com/ 


The Visual End User, a workshop on vi- 
sual languages for end-user and domain- 
specific programming, will take place on 
October 24—25, 1999 at the Ramada Plaza 
Hotel, Old Town Alexandria, Virginia. 
Held in conjunction with the Eighth Work- 
shop on Empirical Studies of Program- 
mers, VEU is a new workshop about end 
users and the way they program com- 
puters, or perform tasks similar to pro- 
gramming. Application areas include 
robot control, spreadsheets and form- 
based languages, structural and architec- 
tural design, programming for children, 
and multimedia authoring. For more in- 
formation, go to http://www.cs.dal.ca/ 
~smedley/veu/. 
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Another Kind of e-book 


technology and generally observing the passing show, what’s the most outrageous thing 

you've ever heard?” I have a ready answer. 

The most outrageous thing I’ve ever heard has only indirect relevance to computer technol- 
ogy, but part of its outrageousness is that it seems to have some relevance to so many different 
subjects. My candidate for the most outrageous statement ever uttered is: 


ae ea 


n the unlikely event that someone asks me, “Mike, in all your years of tracking computer 





You may or may not find it outrageous; it requires some mathematics to be shocked by it, but not 
so much mathematics that it becomes obvious. I happen to fall into that semieducated slot, and 
my first reaction to the equation is, “How could that possibly be true?” followed quickly by, “And 
even if it is, what can it possibly mean?” The equation unites five of the most fundamental 
constants of mathematics: e, i, 7, 0, and 1. It uses the three basic operations: addition, 
multiplication, and exponentiation— and uses each of them exactly once. It ties together 
arithmetic, geometry, logarithms, algebra, integral and differential calculus, and complex numbers. 
It introduces two different transcendental numbers and one imaginary number on the left side of 
the equal sign, and through some magic that just shouldn’t work, makes them all cancel each 
other out, leaving zero on the right side. 

Nineteenth-century mathematician Benjamin Peirce said of this equation, “That is surely true, 
it is absolutely paradoxical; we cannot understand it, and we don’t know what it means. But we 
have proved it, and therefore we know it must be the truth.” 

It’s poetry. In just seven symbols, it packs in an amazingly rich collection of ideas and rela- 
tionships, plus those five constants, three of which are pretty mysterious on their own: 


e The letter e stands for the transcendental number 2.71828..., the base of the natural logarithms, 
the necessary constant in the only function that is its own derivative, and an important num- 
ber in financial calculations. It pops up in the quantification of human perception, in archi- 
tecture, and in the growth patterns of sunflowers, nautilus shells, and spiral galaxies. 

e The Greek letter 1, of course, represents the ratio of the circumference to the diameter of a cir- 
cle, but can be expected to show up in any formula involving curvature or cyclic repetition. 

e The letter i represents the imaginary base, the square root of negative one, the foundation of 
the complex number system. 


What connects these numbers, and how that connection was discovered, is the subject of the 
delightful and very readable book e: The Story of a Number (Princeton University Press, 1993, 
ISBN 0-691-05854-1), by Eli Maor, who teaches the history of mathematics at Loyola University 
in Chicago. The book was just recently released in paperback, with new material on a recent 
discovery regarding prime numbers. Maor tells the story of the rather odd John Napier, who 
changed the way scientists calculated; recounts the birth of differential and integral calculus, 
with all the controversy it engendered; shows how Hamilton’s notation for complex numbers 
made them seem less “imaginary”; and shows the extraordinary chutzpah of Leonhard Euler, 
who plugged imaginary exponents into functions involving the number e, played fast and loose 
with infinities, and took the results seriously when m suddenly appeared in his calculations, 
seemingly from out of nowhere. 

By the end of the book, Maor has told some good stories; shown some remarkable proper- 
ties of e, 7, and 7; and led the reader to see how e, m, and 7 are related and why the outrageous 
equation actually makes sense. 

But best of all, in doing so, he doesn’t make it seem any less outrageous. He doesn’t destroy 
the poetry in analyzing it. I recommend the book to any DDJ reader. 


HilaD Scab 


Michael Swaine 
editor-at-large 
mswaine@swaine.com 
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“CodeBase gives ACT! the fast database access 
that contact management users need.” 
- Michael Plasterer, Director of Development, Symantec 
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Loaded with 
features... 


Multi - Language 
CodeBase 6.4 works with C, C++, Visual Basic, Java, Delphi, 
ODBC and OLE DB. 


Incredible Speed 

Query a million records in 0.49 seconds. Append 10,000 
records in just 0.65 seconds! All this speed in a super- 
compact library that uses very little memory. 


Royalty Free 


Includes standalone, client and server. 


xBASE Compatible 


Multi-user file compatible with FoxPro, dBASE and Clipper 
data, index and memo files. 


Client/Server 

Advanced security features. New easy-to-use tools for 
monitoring database activity and managing user access. 
Incredibly easy installation and setup! 


Portable 
Runs under Windows 98, 95, NT, CE, 3.1, DOS, Mac, 08/2, Solanis, 
SunOS, AIX, CO, Linux, UnixWare, DEC, Alpha, BSDI, HP/UX.. 


Enterprise-Level Power 
Includes transaction processing, logging, backup and recovery 
tools, and intelligent queries. 


And More.... 


Data-Aware controls, full-featured report writer and free 
technical support. Add-ons available for OLE DB, ODBC and 
Delphi BDE plug-in replacement. 


FREE 30 Day Test Drive 


Test drive the new CodeBase 6.4 for 30 days 
with your own code. No risk. No obligation. 
No royalties. Order today! 


Call: 780-437-2410 


Web Site: www.sequiter.com 
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our developers OV es 


absolutely 
their Java™ IDE. 





The rest have discovered the limitations of other developer tools. 
With VisualCafé Database Edition, you’ve got all you need to get 
your job done on time and, who knows, maybe have some 
time leftover for you. Whether you're a seasoned 
Java programmer, or moving to Java from Visual Basic® or 

C++, you'll find VisualCafé easy to learn and use because 
of its visual development environment—complete with 
automated wizards and code helper. In fact, if you’re creating 
serviets, JavaBeans,” or 

deploying comprehensive Vi f 4 

database-driven applications IStld a eC 
with JDBC support, it’s your 

best choice for development. 
It offers Superior speed, robust code, drag-and-drop programming, 

QBE (Query-By-Example) capability, open Java API, and support for 

data binding JFC/Swing. Call or visit our website and request our 


Java hierarchy poster. Join the tens of thousands of developers 
who use VisualCafé. You too may develop an attachment to it. 





Symantec and the Symantec logo are U.S. registered trademarks of Symantec Corporation. VisualCafé is a trademark of Symantec Corporation. Java, JavaBeans and all Java based marks are trademarks or registered trademarks of 
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The #1-selling Java IDE for 3 years running. 





